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CHAPTER 1 


SYSTEM CALLS 


1.1 INTRODUCTION 


The routines that MS-DOS uses to manage system operation and 
resources can be called by any application program. Using 
these system calls makes it. easier to write 
machine-independent programs and increases the likelihood 
that a program will be compatible with future versions of 


MS-DOS. MS-DOS system calls fall into several categories: 
Standard character device I/O 
Memory management 
Process management 
File and directory management 
Microsoft Network calls 
Miscellaneous system functions 


MS-DOS services are invoked by an application by software 
interrupts. The current range of interrupts used for MS-DOS 
is 20H-27H, with 28H-40H reserved. Interrupt 21H is’ the 
function request service, and provides access to a wide 
variety of MS-DOS services. The selection of the Interrupt 
21H function is through a function number placed in the AH 
register by the application. In some cases, the full AX 
register is used to specify the requested function. Each 
interrupt or function request uses values. in various 


registers to receive or return function-specific 
information. 
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1.1.1 System Calls That Have Been Superseded 


Many system calls introduced in versions of MS-DOS’ earlier 
than 2.0 have been Superseded by function requests that are 
simpler to use and make better use of system resources. 
Although MS-DOS still includes these old system calls, they 
should not be used unless it is imperative that a program 


maintain backward-compatibility with the pre-2.0 versions of 
MS-DOS. 


A table of the pre-2.0 system calls and a description of the 
File Control Block (required by some of the old calls) 
appears in Section 1.8, "Old System Calls." 


The first part of this chapter explains how DOS manages its 
resources -- such as memory, files, and processes -- and 
briefly describes the purpose of most of the system calls. 
The remainder of the chapter describes each interrupt and 
function request in detail. The system call descriptions 
are in numeric order, interrupts followed by function 
requests. These descriptions include further detail on how 
MS-DOS manages its resources. 


Chapter 2 of this book describes how to write an MS-DOS 
device driver. Chapters 3, 4, and 5 contain more detailed 
information about MS-DOS, including how it manages’ disk 
space, the control blocks it uses, and how it loads and 
executes relocatable programs (files with an extension of 
oEXE). Chapter 6 describes the Intel(R) object module 
format. Chapter 7 gives some programming hints. 


1.2 STANDARD CHARACTER DEVICE I/O 


The standard character function requests handle all input 
and output to and from character devices such as the 
console, printer, and serial ports. If a program uses these 
function requests, its input and output can be redirected. 


Table 1.1 lists the MS-DOS function requests for managing 
standard character input and output. 
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Table 1.1 Standard Character I/O Function Requests 


01H Read Keyboard Gets a character from standard input 
and Echo and echoes it to standard output. 


02H Display Character Sends a character to standard 
output. 


03H Auxiliary Input Gets a character from standard 
auxiliary. 


04H Auxiliary Output Sends a character to standard 
auxiliary. 


OSH Print Character Sends a character to the standard 
printer. 


06H Direct Console I/O Gets a character from standard input 
or sends a character to standard 


output. 
07H Direct Console Gets a character from standard 
Input input. 
08H Read Keyboard Gets a character from standard 
input. 
O9H Display String Sends a string to Standard output. 
OAH Buffered Keyboard Gets a string from standard input. 
Input 
OBH Check Keyboard Reports on the status of the 
Status standard input buffer. 
OCH Flush Buffer, Empties the standard input buffer 
Read Keyboard and calls one of the other standard 


character I/O function requests. 


Although several of these standard character I/O function 
requests seem to do the same thing, they are distinguished 
by whether they echo characters from standard input to 
standard output or check for control characters. The 
detailed descriptions later in this chapter point out’ the 
differences. 
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1.3 MEMORY MANAGEMENT 


MS-DOS keeps track of which areas of memory are allocated by 
writing a memory control block at the beginning of each area 
of memory. This control block specifies the size of the 
memory area; the name of the process, if any, that owns the 
memory area; anda pointer to the next area of memory. If 
the memory area is not owned, it is available. 


Table 1.2 lists the MS-DOS function requests for managing 
memory. 


Table 1.2 Memory Management Function Requests 


48H Allocate Memory Requests a block of memory. 

49H Free Allocated Frees a block of memory previously 
Memory allocated with 48H. 

4AH Set Block Changes the size of an allocated 


memory block. 


When a process requests additional memory with Function 48H, 
MS-DOS searches for a block of available memory large enough 
to satisfy the request. If it finds such a block of memory, 
it changes the memory control block to show the owning 
process. If the block of memory is larger than _ the 
requested amount, MS-DOS changes the size field of the 
memory control block to the requested amount, writes a new 
memory control block at the beginning of the unneeded 
portion that shows it is available, and updates the pointers 
to add this memory to the chain of memory control blocks. 
MS-DOS then returns the segment address of the first byte of 
the allocated memory to the requesting process. 


When a process releases an allocated block of memory with 
Function 49H, DOS changes the memory control block to show 
that it is available (not owned by any process). 


When a process shrinks an allocated block of memory with 
Function 4AH, DOS builds a memory control block for the 
memory being released and adds it to the chain of memory 
control blocks. When a process tries to expand an allocated 
block of memory with Function 4AH, MS-DOS treats it as a 
request for additional memory; rather than returning the 
segment address of the additional memory to the requesting 
process, however, MS-DOS simply chains the additional memory 
to the existing memory block. 


If MS-DOS can't find a block of available memory large 
enough to satisfy a request for additional memory -- made 
with either Function 48H or Function 4AH -- MS-DOS returns 
an error code to the requesting process. 
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When a program receives control, it should call Function 4AH 
to shrink its initial memory allocation block (the block 
that begins with its Program Segment Prefix) to the minimum 
it requires. This frees unneeded memory and makes the best 
application design for portability to future multitasking 
environments. 


When a program, exits, MS-DOS automatically frees its initial 
memory allocation block before returning control to the 
calling program (COMMAND.COM is usually the calling program 
for application programs). The DOS frees any memory owned 
by the process exiting. 


Any program that changes memory not allocated to it will 
most likely destroy at least one memory management control 
block. This causes a memory allocation error the next time 
MS-DOS tries to use the chain of memory control blocks; the 
only cure is to restart the system. 


1.4 PROCESS MANAGEMENT 


MS-DOS uses several function requests to load, execute, and 
terminate programs. Application programs can use these same 
function requests to manage other programs. 


Table 1.3 lists the MS-DOS function requests for managing 
processes. 


Table 1.3 Process Management Function Requests 


31H Keep Process Terminates a process and returns 
control to the invoking process, 
but keeps the terminated process 
in memory. 


4B00H Load and Execute Loads and executes a program. 


Program 
4B03H Load Overlay Loads a program Overlay without 
executing it. 
4CH End Process Returns control to the invoking 
process. 
4DH Get Return Code Returns a code passed by a child 


of Child Process process when it exits. 


62H Get PSP Returns the segment address of the 
Program Segment Prefix of the 
current process. 
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1.4.1 Loading And Executing A Program 


When a program loads and executes another program with 
Function 4B00H, MS-DOS allocates memory, writes a Program 
Segment Prefix (PSP) for the new program at offset 0 of the 
allocated memory, loads the new program, and passes control 
to it. When the invoked program exits, control returns’ to 
the calling program. 


COMMAND.COM uses Function 4B00H to load and execute command 
files. Application programs have the same degree of control 
over process management as COMMAND.COM. 


In addition to these common features, there are some 
differences in the way MS-DOS loads .COM and .EXE files. 


Loading a .COM Program 


When COMMAND.COM loads and executes a .COM program, it 
allocates all of available memory to the application and 
sets the stack pointer 100H bytes from the end of available 
memory. A .COM program should set up its own stack before 
shrinking its initial memory allocation block with Function 
4AH, because the default stack is in the memory to be 
released. 


If a newly loaded program is allocated all of memory -- as a 
-COM program is -- or requests all of available memory with 
Function 48H, MS-DOS allocated to it the memory occupied by 
the transient part of COMMAND.COM. If the program changes 
this memory, MS-DOS must reload the transient portion of 
COMMAND.COM before it can continue. If a program exits (via 
call 31H, Keep Process) without releasing enough memory, the 
system halts and must be reset. To minimize this 
possibility, a .COM program should shrink its initial 
allocation block with Function 4AH before doing anything 
else, and all programs must release all memory they allocate 
with Function 48H before exiting. 


Loading an .EXE Program 


When COMMAND.COM loads and executes an .EXE program, it 
allocates the size of the program's memory image plus either 
the value in the MAXALLOC field (offset OCH) of the file 
header, if that much memory is available, or the value in 
the MINALLOC field (offset OAH). These fields are set by 
the linker. Before passing control to the .EXE file, MS-DOS 
calculates the correct relocation addresses, based on _ the 
relocation information in the file header. 


For a more detailed description of how MS-DOS loads .COM and 
-EXE files, see Chapters 3 and 4. 
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Executing a Program From Within Another Program 


Because COMMAND.COM takes care of details such as_ building 
complete pathnames, searching the directory path for 
executable files, and relocating .EXE files, the simplest 
way to load and execute a program is to load and execute an 
additional copy of COMMAND.COM, passing it a command line 
that includes the /C switch to invoke the .COM or .EXE file. 
The description of Function 4B00H (Load and Execute Program) 
describes how to do this. 


1.4.2 Loading An Overlay 


When a program loads an overlay with Function 4B03H, it must 
pass to MS-DOS the segment address at which the overlay is 
to be loaded. The program then must call the overlay, and 
the overlay returns directly to the calling program. The 
calling program iS in complete control: MS-DOS does not 
write a PSP for the overlay or intervene in any other way. 


MS-DOS does not check to see if the calling program owns the 
memory where the overlay is to be loaded. If the calling 
program does not own the memory, loading the overlay will 
most likely destroy a memory control block, causing an 
eventual memory allocation error. 


A program that loads an overlay must, therefore, either 
allow room for the overlay when it calls Function 4AH to 
shrink its initial memory allocation block, or should shrink 
its initial memory allocation block to the minimum and then 
use Function 48H to allocate memory for the overlay. 


1.5 FILE AND DIRECTORY MANAGEMENT 


The MS-DOS hierarchical (multilevel) file system is’ similar 
to that of the XENIX operating system. For a description of 
the multilevel directory system and how to use it, see _ the 
MS-DOS User's Reference. 
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1.5.1 Handles 


To create or open a file, a program passes to MS-DOS a 
pathname and the attribute to be assigned to the file. 
MS-DOS returns a 16-bit number called a_ handle. For most 
subsequent actions, MS-DOS requires only this handle to 
identify the file. 


A handle can refer to either a file or a device. MS-DOS 
predefines five standard handles. These handles are always 
open; you needn't open them before you use them. Table 1.4 
lists these predefined handles. 


Table 1.4 Predefined Device Handles 


Handle Standard device Comment 


0 Input Can be redirected from command line 
1 Output Can be redirected from command line 
2 Error 

3 Auxiliary 

4 Printer 


When MS-DOS creates or opens a file, it assigns the first 
available handle. A program can have 20 open handles; this 
includes the five predefined handles, so a program can 
typically open 15 extra files. Any of the five predefined 
handles can be temporarily forced to refer to an alternate 
file or device using function request 46H. 


1.5.2 File-Related Function Requests 


MS-DOS treats a file as a string of bytes; it assumes no 
record structure or access’ technique. An application 
program imposes whatever record structure it needs on this 
string of bytes. Reading from or writing to a file requires 
only pointing to the data buffer and specifying the number 
of bytes to read or write. 
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Table 1.5 lists the MS-DOS function requests for managing 
files. 


Table 1.5 File-—Related Function Requests 


3CH 
3DH 
3EH 
3FH 
40H 


42H 


45H 


46H 


5AH 


5BH 


Create Handle 
Open Handle 
Close Handle 
Read Handle 
Write Handle 


Move File 
Pointer 


Duplicate File 
Handle 


Force Duplicate 
File Handle 
Create 
Temporary File 


Create New File 


Creates a file. 
Opens a file. 
Closes a file. 
Reads froma file. 
Writes to a file. 


Sets the read/write pointer in a 
file. 


Creates a new handle that refers to 
the same file as an existing handle. 


Makes an existing handle refer to 
the same file as another existing 
handle. 

Creates a file with a unique name. 


Attempts to create a file, but fails 
if a file with the same name exists. 
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File Sharing 


Version 3.1 of MS-DOS introduces file sharing, which lets 
more than one process share access to a file. File sharing 
operates only after the Share command has been executed _ to 
load file-sharing support. Table 1.6 lists the MS-DOS 
function requests for sharing files; if file sharing is not. 
in effect, these function requests cannot be used. Function 
3DH, Open Handle, can operate in several modes. 
Compatibility mode is usable without file sharing in effect. 
Here it is referred to in the file-sharing modes, which 
require file sharing to be in effect. 


Table 1.6 File-Sharing Function Requests 


3DH Open Handle Opens a file with one of the 
file-sharing modes. 


440BH IOCTL Retry Specifies how many times an I/O 
operation that fails due to a 
file-sharing violation should be 
retried before Interrupt 24 is 
issued. 


5COOH Lock Locks a region of a file. 


5CO1H Unlock Unlocks a region of a file. 


SYSTEM CALLS Page 1-11 


1.5.3 Device-Related Function Requests 


I/O Control for Devices is implemented with Function 44H 
(IOCTL) ; it includes Several action codes to perform 
different device-related tasks. Some forms of the IOCTL 
function request require that the device driver be written 
to support the IOCTL interface. Table 1.7 lists the MS-DOS 
function requests for managing devices. 


Table 1.7 Device—-Related Function Requests 


4400H,01H IOCTL Data Gets or sets device’ 
description. 


4402H,03H IOCTL Character Gets or sets character 
device control data. 


4404H,05H IOCTL Block Gets or sets block device 
control data. 


4406H,07H IOCTL Status Checks device input or 
Output status. 


4408H IOCTL Is Changeable Checks whether block device 
contains removable medium. 


Some forms of the IOCTL function request can only be used 
with Microsoft(R) Networks; they are listed in Section 1.6, 
"Microsoft Networks." 


1.5.4 Directory-Related Function Requests 


The root directory on a disk has room for a fixed number of 
entries: 64 on a standard single-sided disk, 112 ona 
standard double-sided disk. For hard disks, the number of 
directories is dependent on the DOS partition size. A 
subdirectory is simply a file with a unique attribute; 
there can be aS many subdirectories on a disk as space 
allows. The depth of a directory structure, therefore, is 
limited only by the amount of storage on a disk and the 
maximum pathname length of 64 characters. 


The root directory is identical to the pre-2.0 directory. 
Pre-2.0 disks appear to have only a root directory that 
contains files but no subdirectories. 
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Table 1.8 lists the MS-DOS function requests for managing 
directories. 


Table 1.8 Directory-Related Function Requests 


39H Create Directory Creates a subdirectory. 

3AH Remove Directory Deletes a subdirectory. 

3BH Change Current Changes the current directory. 
Directory 

41H Delete Deletes a file. 
Directory Entry 
(Unlink) 

43H Get/Set File Retrieves or changes the attributes 
Attributes of a file. 
(Chmod ) 

47H Get Current Returns current directory for a 
Directory given drive. 

4EH Find First File Searches a directory for the first 


entry that matches a filename. 


4FH Find Next File Searches a directory for the next 
entry that matches a filename. 


56H Change Renames a file. 
Directory Entry 


57H Get/Set Date/Time Changes the time and date of 
of File last change in a directory entry. 


1.5.5 Directory Entry 


A directory entry is a 32-byte record that includes’ the 
file's name, extension, date and time of last change, and 
size. An entry in a Subdirectory is identical to an entry 
in the root directory. The directory entry is described in 
detail in Chapter 3. 


eon 
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1.5.6 File Attributes 


Table 1.9 describes the file attributes and how they are 
represented in the attribute byte of the directory entry 
(offset OBH). The attributes can be inspected or changed 
with Function 43H (Get/Set File Attributes). 

Table 1.9 File Attributes 

Code Description 


OOH Normal. Can be read or written without restriction. 


01H Read-only. Cannot be opened for write; a file with the 
same name cannot be created. 


02H Hidden. Not found by directory search. 
04H System. Not found by directory Search. 


08H Volume-ID. Only one file can have this attribute; it 
must be in the root directory. 


10H Subdirectory. 


20H Archive. Set whenever the file is changed, cleared 
by the Backup command. 


The Volume-ID (08H) and Directory (10H) attributes cannot be 
changed with Function 43H (Get/Set File Attributes). 
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1.6 MICROSOFT NETWORKS 


A Microsoft Network consists of a server and one or more 
workstations. MS-DOS maintains an asSign list that keeps 
track of which workstation drives and devices have been 
redirected to the server. For a description of operation 
and use of the network, see the Microsoft Networks Manager's 
Guide, and User's Guide. 


Table 1.10 lists the MS-DOS function requests for managing a 
Microsoft Networks workstation. 


Table 1.10 Microsoft Network Function Requests 


4409H IOCTL Is Redirected Checks whether a drive letter 
Block refers to a local or redirected 
drive. 


440AH IOCTL Is Redirected Checks whether a device name 


Handle refers to a local or redirected 
device. 
5E00H Get Machine Name Gets the network name of the 
workstation. 
5E02H Printer Setup Defines a string of control 


characters to be added at the 
beginning of each file sent toa 
network printer. 


5FO02H Get Assign List Gets an entry from the assign 
Entry list that shows the workstation 
drive letter or device name and 
the net name of the directory or 
device on the server to which 
it is reassigned. 


5FO03H Make Assign List Redirects a workstation drive or 
Entry device to a server directory or 
device. 


5FO04H Cancel Assign List Cancels the redirection of a 
Entry workstation drive or device toa 
Server directory or device. 
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1.7 MISCELLANEOUS SYSTEM MANAGEMENT 


The remaining system calls manage other system functions and 
resources such as drives, the clock, and addresses. Table 
1.11 lists the MS-DOS function requests’ for managing 
miscellaneous system resources and operation. 


Table 1.11 Miscellaneous System-Management Function Requests 


ODH Reset Disk Empties all file buffers. 

OFH Select Disk Sets the default drive. 

19H Get Current Disk Returns the default drive. 

1AH Set Disk Transfer Establishes the disk I/O buffer. 
Address 

1BH Get Default Drive Returns disk format data. 
Data 

1CH Get Drive Data Returns disk format data. 

25H Set Interrupt Vector Sets interrupt handler address. 

29H Parse File Name Checks string for valid filename. 

2AH Get Date Returns system date. 

2BH Set Date Sets system date. 

2CH Get Time Returns system time. 

2DH Set Time Sets system time. 

2EH Set/Reset Verify Flag Turns disk verify on or off. 

2FH Get Disk Transfer Returns system disk I/O buffer 
Address address. 

30H Get MS-DOS Version Returns MS-DOS version number. 
Number 

33H Control-C Check Returns Control-C check status. 

35H Get Interrupt Vector Returns address of interrupt 

handler. 


36H Get Disk Free Space Returns disk space data. 

38H Get/Set Country Data Sets current country or retrieves 
country information. 

54H Get Verify State Returns status of disk verify. 


1.8 OLD SYSTEM CALLS 


Most of the system calls that have been superseded deal with 
files. Table 1.12 lists these old calls and the function 
requests that have superseded them. 


Although MS-DOS still includes these old system calls, they 
should not be used unless it is imperative that a program 
Maintain backward-compatibility with the pre-2.0 versions of 
MS-DOS. 
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Table 1.12 Old System Calls and Their Replacements 


Old System Call Has Been Superseded By 
Function Requests Function Requests 

OOH Terminate Program 4CH End Process 

OFH Open File 3DH Open Handle 

10H Close File 3EH Close Handle 


11H Search for First Entry 4EH Find First File 
12H Search for Next Entry 4FH Find Next File 


13H Delete File 41H Delete Directory Entry 
14H Sequential Read 3FH Read Handle 

15H Sequential Write 3DH Open Handle 

16H Create File 3CH Create Handle 


5AH Create Temporary File 
5BH Create New File 


17H Rename File 56H Change Directory Entry 
21H Random Read 3FH Read Handle 
22H Random Write 40H Write Handle 
23H Get File Size 42H Move File Pointer 
24H Set Relative Record 42H Move File Pointer 
26H Create New PSP 4B00H Load and Execute Program 
27H Random Block Read 3FH Read Handle 
28H Random Block Write 40H Write Handle 
Interrupts Function Requests 
20H Program Terminate 4CH End Process 
27H Terminate But Stay 31H Keep Process 
Resident 


1.8.1 File Control Block (FCB) 


The old file-related function requests require that a 
program maintain a File Control Block (FCB) for each file; 
this control block contains such information as the file's 
name, size, record length, and pointer to current record. 
MS-DOS does most of this housekeeping for the newer, 
handle-oriented function requests. 


Some descriptions of the old function requests refer to 
unopened and opened FCBsS. An unopened FCB contains only a 
drive specifier and filename. An opened FCB contains all 
fields filled by Function OFH (Open File). 


The Program Segment Prefix (PSP) includes room for two FCBs 
at offsets 5CH and 6CH. See Chapter 4 for a description of 
the PSP and how these FCBsS are used. Table 1.13 describes 
the fields of the FCB. 


eS 
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Table 1.13 Format of the File Control Block (FCB) 


ES A PR A SSAA ESS ESP 


Offset 
Hex Dec Bytes Name 
OOH 0 1 Drive number 
01H 1 8 Filename 
09H 9 3 Extension 
OCH 12 2 Current block 
OFH 14 2 Record size 
10H 16 4 File size 
14H 20 2 Date of last write 
16H 22 2 Time of last write 
18H 24 8 RESERVED 
20H 32 1 Current record 
21H 33 4 Relative record 


Fields of the FCB 


Drive Number (offset 00H): Specifies the disk drive; 1 
means drive A and 2 means drive B. If the FCB is used to 
create or open a file, this field can be set to 0 to specify 
the default drive; the Open File system call sets the field 
to the number of the default drive. 


Filename (offset 01H): Eight characters, left-aligned and 
padded (if necessary) with blanks. If you specify a 
reserved device name (such aS PRN), do not put a colon at 
the end. 


Extension (offset 09H): Three characters, left-aligned and 
padded (if necessary) with blanks. This field can be all 
blanks (no extension). 


Current Block (offset OCH): Points to the block (group of 
128 records) that contains the current record. This field 
and the Current Record field (offset 20H) make up the record 
pointer. This field is set to 0 by the Open File system 
call. 


Record Size (offset OEH): The size of a logical record, in 
bytes. Set to 128 by the Open File system call. If the 
record size is not 128 bytes, you must set this field after 
opening the file. 


File Size (offset 10H): The size of the file, in bytes. 
The first word of this 4-byte field is the low-order part of 
the size. 
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Date of Last Write (offset 14H): The date the file was 


created or last updated. The year, month, and day are 
mapped into two bytes as follows: 


Offset 15H Offset 14H 
ly|yly|y|y|y|y|M| —s [M|M|mM|p[D|[p|pD|pD| 
15 9 8 5 4 0 


Time of Last Write (offset 16H): The time the file was 
created or last updated. The hour, minutes, and seconds are 
mapped into two bytes as follows: 


Offset 17H Offset 16H 
|H|H|H|H|H|M[M|M| = |[M[M|[M|s|s|s|s|s| 
15 11 10 5 4 0 


Reserved (offset 18H): These fields are reserved for use by 


Current Record (offset 20H): Points to one of the 128 
records in the current block. This field and the Current 
Block field (offset OCH) make up the record pointer. This 
field is not initialized by the Open File system call. You 
must set it before doing a sequential read or write to’ the 
file. 


Relative Record (offset 21H): Points to the currently 
selected record, counting from the beginning of the file 
(starting with 0). This field is not initialized by the 
Open File system call. You must set it before doing a 
random read or write to the file. If the record size is 
less than 64 bytes, both words of this field are used; if 
the record size is 64 bytes or more, only the first three 
bytes are used. 


Note 


If you use the FCB at offset 5CH of the Program Segment 
Prefix, the last byte of the Relative Record field is 


the first byte of the unformatted parameter area that 
starts at offset 80H. This is the default Disk Transfer 
Area. 
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Extended FCB 


The Extended File Control Block is uSed to create or’ search 
for directory entries of files with special attributes. It 
adds the following 7-byte prefix to the FCB: 


Size 
Name (bytes) Offset 
Flag byte (FFH) 1 -07H 
Reserved 5 -06H 
Attribute byte 1 -01H 


File attributes are described earlier in this chapter in 
Section 1.5.6, "File Attributes." 


1.9 USING THE SYSTEM CALLS 


The remainder of this chapter describes how to use the 
system calls in application programs, lists all the calls in 
both numeric and alphabetic order, and describes each call 
in detail. 


1.9.1 Issuing An Interrupt 


MS-DOS reserves Interrupts 20H through 3FH for its own use. 
The table of interrupt handler addresses (vector table) is 
maintained in locations 80H-FCH. Most of the interrupts 
have been superseded by function requests. Descriptions of 
three MS-DOS interrupt handlers (Program Terminate, 
Control-C, and Critical Error) are included in case you must 
write your own routines to handle these interrupts. 


To issue an interrupt, move any required data into’ the 
registers and issue the interrupt. 
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1.9.2 Calling A Function Request 


The function requests call MS-DOS routines to manage system 
resources. Follow this procedure to call a function 
request: 


1. Move any required data into the registers. 
2. Move the function number into AH. 

3. Move the action code, if required, into AL. 
4. Issue Interrupt 21H. 


If your program has a standard Program Segment Prefix, an 


alternative to issuing Interrupt 21H is to execute a long 
call to location 50H in the PSP. 


Whenever possible, it is recommended that the Interrupt 21H 
method be used. 


One other technique supports earlier calling conventions: 
move any required data into the registers; move the 
function number into CL; and execute an intrasegment call 
to location 05H in the current code segment (this location 
contains a long call to the MS-DOS function dispatcher). 
This method can only be used with functions 00H through 24H, 
and always destroys the contents of AX. 


1.9.3 Using The Calls From A High-Level Language 


The system calls can be executed from any high-level 
language whose modules can be linked with assembly language 
modules. In addition to this general technique: 


@ You can use the DOSXQQ function of Pascal-86 to 
call a function request directly. 


@ Use the CALL statement or USER function to execute 


the required assembly-language code from the BASIC 
interpreter. 
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1.9.4 Treatment Of Registers 


When MS-DOS takes control after a function request, it 
switches to an internal stack. Registers not used to return 


information (except AX) are preserved. The calling 
program's stack must be large enough to accommodate the 
interrupt system -- at least 128 bytes in addition to other 
needs. 


1.9.5 Handling Errors 


Most of the newer function requests -- those introduced with 
version 2.0 or later -- set the Carry flag if there is an 
error, and identify the specific error by returning a number 
in AX. Table 1.14 lists these error codes’ and their 
meanings. 


Table 1.14 Error Codes Returned in AX 


Code Meaning 
1 Invalid function code 
2 File not found 
3 Path not found 
4 Too many open files (no open handles left) 
5 Access denied 
6 Invalid handle 
7 Memory control blocks destroyed 
8 Insufficient memory 
9 Invalid memory block address 
10 Invalid environment 
11 Invalid format 
12 Invalid access code 
13 Invalid data 
14 RESERVED 
15 Invalid drive 
16 Attempt to remove the current directory 
17 Not same device 
18 No more files 
19 Disk is write-protected 
20 Bad disk unit 
21 Drive not ready 
22 Invalid disk command 
23 CRC error 
24 Invalid length (disk operation) 
25 Seek error 
26 Not an MS-DOS disk 
27 Sector not found 
28 Out of paper 
29 Write fault 


30 Read fault 
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31 General failure 

32 Sharing violation 

33 Lock violation 

34 Wrong disk 

35 FCB unavailable 

36-49 RESERVED 

50 Network request not supported 
51 Remote computer not listening 
52 Duplicate name on network 

53 Network name not found 

54 Network busy 

55 Network device no longer exists 
56 Net BIOS command limit exceeded 
57 Network adapter hardware error 
58 Incorrect response from network 
59 Unexpected network error 

60 Incompatible remote adapt 

61 Print queue full 

62 Queue not full 

63 Not enough space for print file 
64 Network name was deleted 

65 Access denied 

66 Network device type incorrect 
67 Network name not found 

68 Network name limit exceeded 

69 Net BIOS session limit exceeded 
70 Temporarily paused 

71 Network request not accepted 

72 Print or disk redirection is paused 
73-79 RESERVED 

80 File exists 

81 RESERVED 

82 Cannot make 

83 Interrupt 24 failure 

84 Out of structures 

85 Already assigned 

86 Invalid password 

87 Invalid parameter 

88 Net write fault 


To handle error conditions, put the following statement 
immediately after each call similar to XENIX calls: 


JC <error> 


where <error> represents the label of aan error-handling 
routine that gets the specific error condition by checking 
the value in AX and takes appropriate action. 


Some of the older system calls return a value in a_ register 
that specifies whether the operation was successful. To 
handle such errors, check the error code and take the 
appropriate action. 
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Extended Error Codes 


Newer versions of MS-DOS have added more detailed error 
messages that cannot be used by programs that use the older 
system calls. To avoid incompatibility, MS-DOS maps' these 
new error codes to the old error code that most closely 
matches the new one. 


To make use of these new calls, Function 59H (Get Extended 
Error) has been added. It provides as much detail as 
possible on the most recent error code returned by MS-DOS. 
The description of Function 59H lists the new, more detailed 
error codes and shows how to use this function request. 


1.9.6 System Call Descriptions 


Most system calls require that information be moved into one 
or more registers before the call is issued and return 
information in the registers. The description of each 
system call in this chapter includes the following: 


e A drawing of the 8088 registers that shows’ their 
contents before and after the system call. 


e A more complete description of the register 
contents required before the system call. 


@e A description of the processing performed. 


@ A more complete description of the register 
contents after the system call. 


@e An example of the system call's use. 
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Figure 1.1 is an example of the drawing of the 8088 
registers and how the information is presented. 


ox [Tm a Call 

Bx: 

Cx: 

px. bo pH de Dk 
Return 


Figure 1.1 Example of System Call Description 
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Sample Programs 


The sample programs show only data declarations and the code 
required to use the system calls. Unless stated otherwise, 
each example assumes a common. skeleton that defines’ the 
segments and returns control to MS-DOS. Each sample program 
is intended to be executed as a .COM file. Figure 1.2 shows 
a complete sample program. The unshaded portion shows what 
appears in this chapter; the shaded portions are the common 
skeleton. 


begin: - open_handle filename,0 ; Open the file 
jc error open : Routine not shown 
mov handle,ax : Save handle 

read line: read handle handle,buffer,128 ; Read 128 bytes 

~ je error read ; Routine not shown 

cmp ax,0 * End of file? 
je return : Yes, go home 
mov bx ,ax : No, AX bytes read 
mov buffer [bx] ,"$" ; To terminate string 
display buffer ; See Function 09H 
jmp read line ; Get next 128 bytes 


Figure 1.2 Sample Program With Common Skeleton 


To allow the examples to be more complete programs’ rather 
than isolated uses of the system calls, a macro is defined 
for each system call; these macros, plus some general 
purpose ones, are used in the sample programs. The sample 
program in the preceding figure includes four such macros: 
open_handle, read_handle, display, and end_process. All 
macro definitions are listed at the end of this chapter. 
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The macros assume the environment for a .COM program as 
described in Chapter 4; in particular, they assume that all 
the segment registers contain the same value. To conserve 
space, the macros generally do not protect registers and 
leave error checking to the main code. This keeps' the 
macros fairly short, yet useful. You may find such macros a 
convenient way to include system calls in your’ assembly 
language programs. 


. Error Handling in Sample Programs 


Whenever a system call returns an error code, the sample 
program shows a test for the error condition and a jump to 
an error routine. To conserve space, the error routines 
themselves aren't shown. Some error routines might simply 
display a message and continue processing; in more’ serious 
cases, the routine might display a message and end the 
program (performing any required housekeeping, such as 
closing files). 


Tables 1.15 through 1.18 list the Interrupts and Function 
Requests in numeric and alphabetic order. 


Table 1.15 MS-DOS Interrupts, Numeric Order 


Interrupt Description 

20H Program Terminate 

21H Function Request 
22H Terminate Process Exit Address 
23H Control-C Handler Address 

24H Critical Error Handler Address 

25H Absolute Disk Read 

26H Absolute Disk Write 

27H Terminate But Stay Resident 


28H-3FH RESERVED 


Table 1.16 MS-DOS Interrupts, Alphabetic Order 


Description Interrupt 
Absolute Disk Read 25H 
Absolute Disk Write 26H 
Control-C Handler Address 23H 
Critical Error Handler Address 24H 
Function Request 21H 
Program Terminate 20H 
RESERVED 28H-3FH 


Terminate Process Exit Address 22H 
Terminate But Stay Resident 27H 
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Table 1.17 MS-DOS Function Requests, Numeric Order 


Function Description 
00H Terminate Program 
01H Read Keyboard And Echo 
02H Display Character 
03H Auxiliary Input 
04H Auxiliary Output 
05H Print Character 
06H Direct Console I/0 
07H Direct Console Input 
08H Read Keyboard 
09H Display String 
OAH Buffered Keyboard Input 
OBH Check Keyboard Status 
OCH Flush Buffer, Read Keyboard 
ODH Reset Disk 
OEH Select Disk 
OFH Open File 
10H Close File 
11H Search For First Entry 
12H Search For Next Entry 
13H Delete File 
14H Sequential Read 
15H Sequential Write 
16H Create File 
17H Rename File 
18H RESERVED 
19H Get Current Disk 
1AH Set Disk Transfer Address 
1BH Get Default Drive Data 
1CH Get Drive Data 
1DH-20H RESERVED 
21H Random Read 
22H Random Write 
23H Get File Size 
24H Set Relative Record 
25H Set Interrupt Vector 
26H Create New PSP 
27H Random Block Read 
28H Random Block Write, 
29H Parse File Name | 
2AH Get Date 
2BH Set Date 
2CH Get Time 
2DH Set Time 
2EH Set/Reset Verify Flag 
2FH Get Disk Transfer Address 
30H Get MS-DOS Version Number 
31H Keep Process 
32H RESERVED 
33H Control-C Check 


34H RESERVED 
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35H 

36H 

37H 

38H 

39H 

3AH 

3BH 

3CH 

3DH 

3EH 

3FH 

40H 

41H 

42H 

43H 

4400H,4401H 

4402H,4403H 

4404H,4405H 

4406H,4407H 

4408H 

4409H 

440AH 

440BH 

45H 

46H 

47H 

48H 

49H 

4AH 

4B00H 

4B03H 

4CH 

ADH 

4EH 

4FH 
50H-53H 

54H 

55H 

56H 

57H 

58H 

59H 

5AH 

5BH 

5C00H 

5C01H 

5DH 

5E00H 

5E0 2H 

5F02H 

5F03H 

5F0 4H 

60H-61H 

6 2H 

63H-7FH 


Get Interrupt Vector 
Get Disk Free Space 
RESERVED 

Get/Set Country Data 
Create Directory 
Remove Directory 
Change Current Directory 
Create Handle 

Open Handle 

Close Handle 

Read Handle 


Write 


Handle 


Delete Directory Entry 
Move File Pointer 
Get/Set File Attributes 


IOCTL 
TOCTL 
IOCTL 
IOCTL 
IOCTL 
IOCTL 
IOCTL 
IOCTL 


Data 

Character 

Block 

Status 

Is Changeable 

Is Redirected Block 
Is Redirected Handle 
Retry 


Duplicate File Handle 


Force 


Duplicate File Handle 


Get Current Directory 
Allocate Memory 

Free Allocated Memory 

Set Block 

Load and Execute Program 
Load Overlay 

End Process 

Get Return Code Child Process 
Find First File 

Find Next File 

RESERVED 

Get Verify State 

RESERVED 

Change Directory Entry 
Get/Set Date/Time of File 
Get/Set Allocation Strategy 
Get Extended Error 

Create Temporary File 
Create New File 


Lock 


Unlock 


RESERVED 

Get Machine Name 

Printer Setup 

Get Assign List Entry 
Make Assign List Entry 
Cancel Assign List Entry 
RESERVED 

Get PSP 

RESERVED 
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Tab)~ 1.18 MS-DOS Function Requests, Alphabetic Order 


Function 


48H 
03H 
04H 
OAH 
5F04H 
3BH 
56H 
OBH 
10H 
3EH 
33H 
39H 
16H 
3CH 
5BH 
26H 
5AH 
41H 
13H 
06H 
07H 
02H 
09H 
45H 
4CH 
4EH 
4FH 
OCH 
46H 
49H 
5F 02H 
47H 
19H 
2AH 
1BH 
36H 
2FH 
1CH 
59H 
23H 
35H 
5E01H 
30H 
62H 
4DH 
2CH 
54H 
58H 
38H 
57H 


Description 


Allocate Memory 
Auxiliary Input 
Auxiliary Output 
Buffered Keyboard Input 
Cancel Assign List Entry 
Change Current Directory 
Change Directory Entry 
Check Keyboard Status 
Close File 

Close Handle 

Control-C Check 

Create Directory 

Create File 

Create Handle 

Create New File 

Create New PSP 

Create Temporary File 
Delete Directory Entry 
Delete File 

Direct Console I/O 
Direct Console Input 
Display Character 
Display String 

Duplicate File Handle 
End Process 

Find First File 

Find Next File 

Flush Buffer, Read Keyboard 
Force Duplicate File Handle 
Free Allocated Memory 
Get Assign List Entry 
Get Current Directory 
Get Current Disk 

Get Date 

Get Default Drive Data 
Get Disk Free Space 

Get Disk Transfer Address 
Get Drive Data 

Get Extended Error 

Get File Size 

Get Interrupt Vector 

Get Machine Name 

Get MS-DOS Version Number 
Get PSP 


Get Return Code Of Child Process 


Get Time 

Get Verify State 

Get/Set Allocation Strategy 
Get/Set Country Data 
Get/Set Date/Time Of File 
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43H 
4404H,4405H 
4402H,4403H 
4400H,4401H 
4408H 
4409H 
440AH 
440BH 
4406H,4407H 
31H 
4B00H 
4B03H 
5C00H 
5F0 3H 
42H 
OFH 
3DH 
29H 
05H 
5E0 2H 
27H 
28H 
21H 
22H 
3FH 
08H 
01H 
3AH 
17H 
18H 
1BH-20H 
32H 
34H 
37H 
50H-53H 
55H 
60H-61H 
63H-7FH 
ODH 
11H 
12H 
OEH 
14H 
15H 
4AH 
2BH 
1AH 
25H 
24H 
2DH 
2EH 
00H 
5CO1H 
40H 


Get/S 
IOCTL 
IOCTL 
IOCTL 
TOCTL 
IOCTL 
IOCTL 
IOCTL 
IOCTL 
Keep 
Load 
Load 
Lock 
Make 
Move 
Open 
Open 
Parse 
Print 
Print 
Rando 
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et File Attributes 
Block 
Character 
Data 
Is Changeable 
Is Redirected Block 
Is Redirected Handle 
Retry 
Status 
Process 
and Execute Program 
Overlay 


Assign List Entry 
File Pointer 

File 

Handle 

File Name 
Character 

er Setup 

m Block Read 


Random Block Write 
Random Read 
Random Write 


Read 
Read 
Read 


Handle 
Keyboard 
Keyboard And Echo 


Remove Directory 
Rename File 
RESERVED 
RESERVED 
RESERVED 
RESERVED 
RESERVED 
RESERVED 
RESERVED 
RESERVED 
RESERVED 


Reset 
Searc 
Searc 
Selec 
seque 
Seque 
Set B 


Disk 

h For First Entry 
h For Next Entry 
t Disk 

ntial Read 

ntial Write 

lock 


Set Date 
Set Disk Transfer Address 


Set I 
Set 


nterrupt Vector 


Relative Record 


Set Time 

Set/Reset Verify Flag 
Terminate Program 
Unlock 

Write Handle 
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A devailed description of each system call follows. They 
are listed in numeric order; the interrupts are described 
first, then the function requests. 


Note: Unless otherwise stated, all numbers in the system 
call descriptions--both text and code--are in hexadecimal. 


1.10 INTERRUPTS 


The following pages describe Interrupts 20H-27H. 


SYSTEM CALLS | Interrupt 20H Page 1-32 


Program Terminate (Interrupt 20H) 


AX: 
BX: 
Cx: 
OX: 


Call 
cs 


Segment address of Program Segment 
Prefix 


Return 
None 


Interrupt 20H terminates the current process and returns 
control to its parent process. All open file handles are 
closed and the disk cache is cleaned. CS must contain the 


segment address of the Program Segment Prefix when this 
interrupt is issued. 


Interrupt 20H is provided only for compatibility with 
versions of MS-DOS prior to 2.0. New programs should use 
Function Request 4CH, End Process, which permits returning a 
completion code to the parent process and does not require 


CS to contain the segment address of the Program Segment 
Prefix. 


The following exit addresses are restored from the Program 
Segment Prefix: 


Offset Exit Address 

OAH Program terminate 
OEH Control-C 

12H Critical error 


ae 
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Note 


Close all files that have changed in length before 
issuing this interrupt. If a changed file is not 


closed, its length is not recorded correctly in the 
directory. See Functions 10H and 3EH for a description 
of the Close File system calls. 


Macro Definition: terminate macro 
int 20H 
endm 


Example 


The following program displayS a message and returns’ to 
MS-DOS. It uses only the opening portion of the sample 
program skeleton shown in Figure 1.2: 


message db "displayed by INT20H example". ODH, OAH, "S" 


begin: display message ;see Function 09H 
terminate ;THIS INTERRUPT 
code ends 
end Start 
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Function Request (Interrupt 218) 


Call 
AH 
Function number 


Other registers 
As specified in individual function 


Return 
As specified in individual function 


Interrupt 21H causes MS-DOS to carry out the function 
request whose number is in AH. See Section 1.11, "Function 
Requests," for a description of the MS-DOS functions. 
Example 


To call the Get Time function: 


mov ah, 2CH ;Get Time is Function 2CH 
int 21H *;MS-DOS function request 
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Terminate Process Exit Address (Interrupt 22H) 


When a program terminates, MS-DOS transfers control to the 
routine that starts at the address in the Interrupt 22H 
entry in the vector table. When MS-DOS creates a program 
segment, it copies this address into the PSP starting at 
offset OAH. 


This interrupt must never be issued by a user program; it 
is issued only by MS-DOS. Tf you must write your own 
terminate interrupt handler, use Function Request 35H (Get 
Interrupt Vector) to get the address of the standard 
routine, save the address, then use Function Request 25H 
(Set Interrupt Vector) to change the Interrupt 22H entry in 
the vector table to point to your routine. 
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Control-C Handler Address (Interrupt 23H) 


When a user types Control-C Or Control-Break (on 
IBM-compatibles), MS-DOS transfers control as soon as 
possible to the routine that starts at the address in the 
Interrupt 23H entry in the vector’ table. When MS-DOS 
creates a program segment, it copies the address currently 
in the interrupt table into the PSP starting at offset OEH. 


This interrupt must never be issued by a user. program; it 
is issued only by MS-DOS. If you must write your own 
Control-C interrupt handler, use Function Request 35H (Get 
Interrupt Vector) to get the address of the standard 
routine, save the address, then use Function Request 25H 
(Set Interrupt Vector) to change the Interrupt 23H entry in 
the vector table to point to your routine. 


If the Control-C routine preserves all registers, it can end 
with an IRET instruction (return from interrupt) to continue 
program execution. If the user-written interrupt program 
returns with a long return, the carry flag is used to 
determine whether or not the program will abort. If the 
carry flag is set, it will be aborted; otherwise, execution 
will continue as with a return by IRET. If the user-written 
Control-Break interrupt uses function calls 09H or OAH, then 
Control-C, Return, and Line Feed are output. If execution 
continues with an IRET instruction, I/O continues from the 
start of the line. 


When the interrupt occurs, all registers are set to _ the 
value they had when the original call to MS-DOS was made. 
There are no restrictions on what a Control-C handler can do 
—- including MS-DOS function calls -- as long as the 
registers are unchanged if IRET is used. 


If Function 09H or OAH (Display String or Buffered Keyboard 
Input) is interrupted by Control-C, the three-byte sequence 
03H-ODH-OAH (usually displayed as C followed by a carriage 
return) iS sent to the display and the function resumes at 
the beginning of the next line. 


If a program creates a second PSP and executes a_e second 
program -- uSing Function 4B00H (Load and Execute Program), 
for example -- and the second program changes the Control-C 
address in the vector table, MS-DOS restores the Control-C 
vector to its original value before returning control to the 
calling program. 


\ 
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Critical Error Handler Address (Interrupt 24H) 


If a critical error occurs during execution of an I/O 
function request -- this usually means a fatal disk error -- 
MS-DOS transfers control to the routine that starts at the 
address in the Interrupt 24H entry in the vector table. 
When MS-DOS createS a program segment, it copies’ this 
address into the PSP Starting at offset 12H. 


This interrupt must never be issued by a user program; it 
is issued only by MS-DOS. If you must write your own 
critical error interrupt handler, use Function Request 35H 
(Get Interrupt Vector) to get the address of the standard 
routine, save the address, then use Function Request 25H 
(Set Interrupt Vector) to change the Interrupt 24H entry in 
the vector table to point to your routine. 


Interrupt 24H is not issued if a failure occurs’ during 
execution of Interrupt 25H (Absolute Disk Read) or Interrupt 
26H (Absolute Disk Write). These errors are handled by the 
error routine in COMMAND.COM that retries the disk 
operation, then gives the user the choice of aborting, 
retrying the operation, or ignoring the error. 


The following topics describe the requirements) of an 
Interrupt 24H routine, the error codes, registers, and 
stack. 


1.10.1 Conditions Upon Entry 


After retrying an I/O error three times, MS-DOS’ issues 
Interrupt 24H. The interrupt handler receives control with 
interrupts disabled. AX and DI contain error codes, and _ BP 
contains the offset (to the Segment address in SI) of a 
Device Header control block that describes the device on 
which the error occurred. 


1.10.2 Requirements For An Interrupt 24H Handler 


To use the MS-DOS critical error handler to issue the 
"Abort, Retry, or Ignore" prompt and get the user's 
response, the first thing a user-written critical error 
handler should do is push the flags and execute a far call 
to the address of the standard Interrupt 24H handler (the 
user program that changed the Interrupt 24H vector should 
have saved this address). After the user responds to the 
prompt, MS-DOS returns control to the user-written routine. 
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NOTE: There are source applications which will have trouble 
with this as it changes the stack frame. 


The error handler can do its processing now, but before it 
does anything else it must preserve BX, CX, DX, DS, ES, SS, 
and SP. Only function calls 01-0CH inclusive and 59H may be 
used (if it uses any others, the MS-DOS stack is destroyed 
and MS-DOS is left in an unpredictable state), nor should it 
change the contents of the Device Header. 


If an Interrupt 24H routine returns to the user program 
(rather than returning to MS-DOS), it must restore the user 
program's registers -- removing all but the last three words 
from the stack -- and issue an IRET. Control returns to the 
statement immediately following the I/O function request 
that resulted in the error. This leaves MS-DOS in an 
unstable state until a function request above OCH is called. 


User Stack 


The user stack is in effect, and contains the following 
(starting with the top of the stack): 


IP MS-DOS registers from issuing Interrupt 24H 
CS 
FLAGS 


AX User registers at time of original 
BX INT 21H 


IP From the original INT 21H 
cS from the user to MS-DOS 


The registers are set such that if the user-written error 


handler issues an IRET, MS-DOS responds according to the 
value in AL: 


AL Action 


0 Ignore the error. 

1 Retry the operation. 

2 Abort the program by issuing Interrupt 23H. 
3 Fail the system call that is in progress. 


Note that the ignore option may cause unexpected results as 
it causes MS-DOS to believe that an operation completed 
successfully when it didn't. 
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Disk Error Code in AX 


If bit 7 of AH is 0, the error occurred on a disk drive. AL 
contains the failing drive (0O=A, 1=B, etc.). Bit 0 of AH 
specifies whether the error occurred during a read or write 
operation (0=read, l=write), and bits 1 and 2 of AH identify 
the area of the disk where the error occurred: 


Bits 

2-1 Location of error 

00 MS-DOS area 

O01 File Allocation Table 
10 Directory 

11 Data area 


Bits 3-5 of AH specify valid responses to the error prompt: 


Bit Value Response 

3 0 Fail not allowed 
1 Fail allowed 

4 0 Retry not allowed 
1 Retry allowed 

5 0 Ignore not allowed 
1 Ignore allowed 


If Retry is specified but not allowed, MS-DOS changes it to 
Fail. If Ignore is specified but not allowed, MS-DOS 
Changes it to Fail. If Fail is specified but not allowed, 
MS-DOS changes it to Abort. The Abort response is always 
allowed. 


Other Device Error Code in AX 


If bit 7 of AH is 1, either the memory image of the File 
Allocation Table (FAT) is bad or an error occurred on a 
character device. The device header pointed to by _ BP:SI 
contains a word of attribute bits that identify the type of 
device and, therefore, the type of error. 


The word of attribute bits is at offset 04H of the Device 
Header. Bit 15 specifies the type of device (0=block, 
l=character). 


If bit 15 is 0 (block device), the error was a bad memory 
image of the FAT. 


If bit 15 is 1 (character device), the error waS on a 
character device. DI contains the error code, the contents 
of AL are undefined, and bits 0-3 of the attribute word have 
the following meaning: 


SYSTEM CALLS 


Bit Meaning 


Current 
Current 
Current 
Current 


WN FH © 


See Chapter 2 for 


Error Code in DI 


The high byte of DI is undefined. 


Interrupt 24H 


If Set 


Standard input 
standard output 
null device 
clock device 


a complete description 
Header control block. 


following error codes: 


Error 


Code Description 


AWPrPrOBDADHUAWNEF O 


A user-written Interrupt 24H handler can 


use 


of 
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the Device 


Attempt to write on write-protected disk 
Unknown unit 
Drive not ready 
Unknown command 
CRC error in data 
Bad drive request structure length 
Seek error 

Unknown media type 
Sector not found 
Printer out of paper 
Write fault 

Read fault 

General failure 


Function 


The low byte contains the 


59H 


(Get Extended Error) to get detailed information about the 
error that caused the interrupt to be issued. 
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Absolute Disk Read (Interrupt 25H) 


ax: [an | om Call 
x: | se | AL 
ox: | coe | a Drive number 
a ce DS : BX 
a eae Disk Transfer Address 
ee = 
Number of sectors 
| DX 
ee ee od Beginning relative sector 
a ae 
[race | RAGS 
Return 
| cs AL 
Error code if. CF=1 
bes SO oe all FlagsL 
| ES CF = 0 if successful 


1 if not successful 


The registers must contain the following: 


AL Drive number (0O=A, 1=B, etc.). 

BX Offset of Disk Transfer Address 
(from Segment address in DS). 

CX Number of sectors to read. 

DX Beginning relative sector. 


Warning 


It is strongly recommended that the use of this 
function be avoided unless absolutely necessary. 


Access to files should be done through the normal 
MS-DOS function requests. There is no guarantee of 
upward compatibility for the Absolute Disk I/O in 
future releases of MS-DOS. 


This interrupt transfers control to the device driver. The 
number of sectors specified in CX is read from the disk to 
the Disk Transfer Address. Its requirements and processing 
are identical to Interrupt 26H, except data is read rather 
than written. Very little checking is done on the user's 
input parameters; therefore, care must be used to make sure 
they are reasonable. Failure to do this may cause strange 
results or a system crash. 
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Note 


All registers except the segment registers are 


destroyed by this call. Be sure to save any registers 
your program uses before issuing the interrupt. 


The system pushes the flags at the time of the call; they 
are still there upon return. Be Sure to pop the stack upon 
return to prevent uncontrolled growth. 


If the disk operation was successful, the Carry Flag (CF) is 
0. If the disk operation was not successful, CF is 1 and AL 
contains the MS-DOS error code (see Interrupt 24H earlier in 
this section for the codes and their meanings). 


Macro Definition: 
abs disk_read macro disk,buffer,num_sectors,first sector 


MOV al,disk 

Mov bx,offset buffer 
MOv cx,num_ sectors 
MOV dx,first sector 
int 25H 

popf 

endm 


Example 


The following program copies the contents of a_ single-sided 
disk in drive A to the disk in drive B. 


prompt db "Source in A, target in B",0DH,OAH 
db "Any key to start. $" 
first dw 0 
buffer db 60 dup (512 dup (?)) 60 sectors 
begin: display prompt :;see Function 09H 
read_kbd ;see Function 08H 
mOv cx,6 ;copy 6 groups of 
760 sectors 
copy: push cx ;save the loop counter 


abs disk read 0,buffer,60,first ;THIS INTERRUPT 
abs disk write 1,buffer,60,first ;see INT 26H 
add first,60 :do the next 60 sectors 
pop cx ;restore the loop counter 
loop copy 
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Absolute Disk Write (Interrupt 26H) 


AX: 
BX: 
Cx: 
DX: 


Drive number 
DS : BX 
Disk Transfer Address 
CX 
Number of sectors 
DX 
Beginning relative sector 


Return 
AL 
Error code if CF‘= 1 
FLAGSL 
CF = 0 if successful 
1 if not successful 


Warning 


It is strongly recommended that the use of this 
function be avoided unless absolutely necessary. 


Access to files should be done through the normal 
MS-DOS function requests. There is no guarantee of 
upward compatibility for the Absolute Disk I/O in 
future releases of MS-DOS. 


The registers must contain the following: 


AL Drive number (0O=A, 1=B, etc.). 

BX Offset of Disk Transfer Address 
(from segment address in DS). 

CX Number of sectors to write. 

DX Beginning relative sector. 


This interrupt transfers control to MS-DOS. The number of 
sectors specified in CX is written from the Disk Transfer 
Address to the disk. Its requirements and processing are 
identical to Interrupt 25H, except data is written to the 
disk rather than read from it. Very little checking is done 
on the user's input parameters; therefore, care must be 
used to make sure they are reasonable. Failure to do this 
May cause strange results or a system crash. 
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Note 


All registers except the segment registers are 


destroyed by this call. Be Sure to save any registers 
your program uses before issuing the interrupt. 


The system pushes the flags at the time of the call; they 
are still there upon return. Be sure to pop the stack upon 
return to prevent uncontrolled growth. 


Tf the disk operation was successful, the Carry Flag (CF) is 
0. If the disk operation was not successful, CF is 1 and AL 
contains the MS-DOS error code (see Interrupt 24H for the 
codes and their meanings). 


Macro Definition: 
abs disk write macro disk,buffer,num_sectors,first_sector 


Mov al,disk 

mov bx,offset buffer 
mov cx,num_ sectors 
mov dx,first sector 
int 26H 

popf 

endm 


Example 


The following program copies the contents of a_ single-sided 
disk in drive A to the disk in drive B, verifying each 
write. It uses a buffer of 32K bytes. 


off equ 0 
on equ 1 
prompt db "Source in A, target in B",0DH,0AH 
db "Any key to start. $" 
first dw 0 
buffer db 60 dup (512 dup (?)) 60 sectors 
begin: display prompt ;see Function 09H 
read kbd ;see Function 08H 
verify on ;see Function 2EH 
MOV cx,6 ;copy 6 groups of 60 sectors 
copy: push cx ssave the loop counter 


abs disk read 0,buffer,60,first ;see INT 25H 
abs disk write 1,buffer,60,first ;THIS INTERRUPT 


add first,60 :do the next 60 sectors 
pop cx s;restore the loop counter 
loop copy 


verify off ;see Function 2EH 
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Terminate But Stay Resident (Interrupt 27H) 
AX: Call 
CS :DX 
Pointer to first byte following 
last byte of code. 


BX: 
CX: 
DX: 


Return 
None 


Interrupt 27H makeS a program up to 64K in size remain 
resident after it terminates. It is often used to install 
device-specific interrupt handlers. 


This interrupt is provided only for compatibility with 
versions of MS-DOS prior to 2.0. You should use Function 
31H (Keep Process), which lets programs larger than 64K 
remain resident and allows return information to be passed, 
to install a resident program unless it is absolutely 
imperative that your program be compatible with pre-2.0 
versions of MS-DOS. 


DX must contain the offset (from the segment address in CS) 
of the first byte following the last byte of code in the 
program. When Interrupt 27H is executed, the program 
terminates and control returns to DOS, but the program is 
not overlaid by other programs. Files left open are not 
closed. When the interrupt is called, CS must contain the 
segment address of the Program Segment Prefix (the value of 
DS and ES when execution started). 


This interrupt must not be used by .EXE programs that are 
loaded into high memory. It restores the Interrupt 22H, 
23H, and 24H vectors, so it cannot be used to install new 
Control-C or critical error handlers. 
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Macro Definition: stay resident macro last_instruc 
mov dx,offset last instruc 


inc dx 
int 27H 
endm 


Example 


Because the most common use of this call is to install a 
machine-specific routine, an example is not shown. The 
macro definition shows the calling syntax. 


1.11 FUNCTION REQUESTS 


The following pages describe function calls 00H-62H. 
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Terminate Program (Function 00H) 


AX: 
BX: 
CX: 
DX: 


Call 

AH = 00H 

CS 
Segment address of 
Program Segment Prefix 


Return 
None 


Function 00H is called by Interrupt 20H; it performs 
same processing. 


The CS register must contain the segment address of 
Program Segment Prefix before you call this interrupt. 


the 


the 


The following exit addresses are restored from the specified 
offsets in the Program Segment Prefix: 


Offset 


OAH 
0OEH 
12H 


Exit Address 


Program terminate 
Control-C 
Critical error 


All file buffers are flushed to disk. 


Warning 


Close all files that have changed in length before 
calling this function. If a changed file is not 


closed, its length is not recorded correctly in the 
directory. See Function 10H for a description of the 
Close File system call. 
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Macro Definition: terminate program macro 


XOr ah,ah 
int 21H 
endm 


Example 

The following program displays a message and returns’ to 
MS-DOS. It uses only the opening portion of the sample 
program skeleton shown in Figure 1.2. 


message db "Displayed by FUNCOOH example", ODH,OAH,"S" 


; 

begin: display message ;see Function 09H 
terminate program ;THIS FUNCTION 

code ends 


end start 
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Read Keyboard and Echo (Function 018) 


AX: 
BX: 
Cx: 
DX: 
Return 
AL 

Character typed 


Function O1H waits for a character to be read from standard 
input, then echoes the character to standard output and 
returns it in AL. If the character is Control-C, Interrupt 
23H is executed. 


Macro Definition: read _ kbd_and_echo macro 
mov ah, O1H 
int 21H 
endm 


Example 


The following program displays and prints characters as they 
are typed. If Return is pressed, the program sends a Line 
Feed-Carriage Return sequence to both the display and _ the 
printer. 


begin: read kbd and echo ;THIS FUNCTION 
print char al ;see Function 05H 
cmp al,ODH sis it a CR? 
jne begin ;no, print it 
print _char OAH ;see Function 05H 
display char OAH ;see Function 02H 


jmp begin sget another character 
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Display Character (Function 02H) 


Call 
AH = 02H 
DL 
Character to be displayed 


Return 
None 


Function 02H sends the character in DL to standard output. 
If Control-C is typed, Interrupt 23H is issued. 


Macro Definition: display char macro character 


MOV dl,character 
MOV ah,02H 

int 21H 

endm 


Example 


The following program converts lowercase characters’ to 
uppercase before displaying them. 


begin: read_kbd ;see Function 08H 

cmp al,"a" 

31 uppercase ;don't convert 

cmp al,"z" 

19 uppercase ;don't convert 

sub al, 20H sconvert to ASCII code 

;for uppercase 

uppercase: display char al ;THIS FUNCTION 


jmp begin: ;get another character 
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Auxiliary Input (Function 038) 


Call 
AH = 03H 


Return 
AL 
Character from auxiliary device 


Function 03H waits for a character from standard auxiliary, 
then returns the character in AL. This system call does not 
return a Status or error code. 


Tf a Control-C has been typed at console input, Interrupt 
23H is issued. 


Macro Definition: aux_input macro 
mov ah,03H 
int 21H 
endm 


Example 


The following program prints characters as they are received 
from the auxiliary device. It stops printing when an 
end-of-file character (ASCII 26, or Control-Z) is received. 


begin: aux input ;THIS FUNCTION 
cmp al,1AH send of file? 
je return syes, all done 
print char al s:see Function 05H 


jmp begin sget another character 
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Auxiliary Output (Function 04H) 


AX: fe ABE 


Bx: 
Cx: 
Dx: 


Function 


Call 
AH = 04H 
DL 
Character for auxiliary device 


Return 
None 


04H sends the character in DL to standard 


auxiliary. This system call does not return a status or 
error code. 


If a Control-C has been typed at console input, Interrupt 
23H is issued. 


Macro Definition: aux_output macro character 


Example 


mov dl,character 
mov ah,04H 

int 21H 

endm 


The following program gets a series of strings of up to 80 
bytes from the keyboard, sending each to the auxiliary 


device. 
string 


begin: 


send it: 


It stops when a null string (CR only) is typed. 


db 81 dup(?) ;Ssee Function OAH 

get string 80,string -see Function OAH 

cmp string[1],0 snull string? 

je return syes, all done 

mov cx, word ptr string[1l] ;get string length 

mov bx,0 set index to 0 

aux output string [bx+2] *THIS FUNCTION 

inc bx ;bump index 

loop send it send another character 
jmp begin sget another string 
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Print Character (Function 058) 


AX: 
BX: 


Call 
AH = 05H 
DL 
Character for printer 


Cx: 
DX: 


Return 


a 
| ee {| | 
pice | | 
pow |e 
ae eel 
| er 
a a None 
ae ae 
pe 
| Fiacsy | Fiacsi | 
| cs 
Se ae 
comet cas! 
| es 


Function 05H sends the character in DL to the standard 
printer. If Control-C has been typed at console input, 
Interrupt 23H is issued. This function request does not 
return a Status or error code. 


Macro Definition: print char macro character 
- mov dl,character 
mMOv ah,05H 
int 21H 
endm 


Example 


The following program prints a walking test pattern on the 
printer. It stops if Control-C is pressed. 


line_num db 0 
begin: MOv cx,60 sprint 60 lines 
start line: mov bl1,33 ;first printable ASCII 


scharacter (!) 
add bl,line num ;to offset one character 


push cx ;Save number-of-lines counter 

mov cx,80 ;loop counter for line 
print_it: print char bl ;THIS FUNCTION 

inc bl smove to next ASCII character 

cmp b1,126 slast printable ASCII 


scharacter (7) 
jl no_reset ;not there yet 
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no_reset: 
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loop print_it 
print _char ODH 
print char OAH 
inc  line_num 
pop CX 

loop start line 


;print another character 
;Carriage return 

;line feed 

to offset 1st char. of line 
;restore #-of-lines counter 
sprint another line 


a 
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Direct Console I/O (Function 06H) 


AX: Call 

BX: AH = 06H 
Cx: DL 

DX: See text 


= aa 
oe BE ae al Return 
fF AL 
| If DL = FFH before call, 
ee then zero flag not set means AL 

; has character from standard input. 
Pee ae) Zero flag set means there was not 
a character to get, and AL = 0 


The action of Function 06H depends on the value in DL _ when 
the function is called: 


Value in DL Action 


FFH If a character has been read from standard 
input, it is returned in AL and the zero flag 
is cleared (0); if a character has not been 
read, the zero flag is set (1). 


Not FFH The character in DL is sent to standard 
output. 


This function does not check for Control-C. 


Macro Definition: dir console io macro switch 
mov dl,switch 
mov ah,06H 
int 21H 
endm 
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Example 


The following program sets the system clock to 0 and 
continuously displays the time. When any character is 
typed, the display freezes; when any character is’ typed 
again, the clock is reset to 0 and the display starts again. 


time db "00:00:00.00",0DH,0AH,"S" ;see Function O9I 
: :for explanation of $ 
begin: set_ time 0,0,0,0 :see Function 2DH 
read_clock: get time ;see Function 2CH 

byte to dec ch,time 7see end of chapter 


byte to dec cl,time[3] ;see end of chapter 
byte to dec dh,time[6] ;see end of chapter 
byte to dec dl,time[9] ;see end of chapter 


display time ;see Function 09H 
dir console io FFH ;THIS FUNCTION 
cmp al,0 scharacter typed? 
jne stop syes, stop timer 
jmp read clock 7no, keep timer 
srunning 
stop: read_ kbd 7see Function 08H 


jmp begin ;start over 


Pn 
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Direct Console Input (Function 07H) 


AX: Call 
BX: AH = 07H 
Cx: 
Dx: 
Eee! peturn 
Ce se 
ae Tia Character from keyboard 
a ae 
ee 
rags. | Fiacs:. | 
ee 
ee 
fe ee 
a ae 


Function 07H waits for a character to be read from standard 
input, then returns it in AL. This function does not echo 
the character or check for Control-C. (For a keyboard input 
function that echoes or checks for Control-C, see Function 
O1H or 08H.) 


Macro Definition: dir console input macro 
= - mov ah,07H 
int 21H 
endm 


Example 
The following program prompts for a password (8 characters 
maximum) and places the characters into a string without 


echoing them. 


password db _ 8 dup(?) 


prompt db "Password: $" ;see Function 09H for 
7explanation of §$ 
begin: display prompt ssee Function 09H 
mov cx,8 smaximum length of password 
xOr bx,bx so BL can be used as index 
get_pass: dir console _ input ;THIS FUNCTION 
cmp al,0ODH swas it a CR? 
je return syes, all done 
mov password [bx],al sno, put character in string 
inc bx sbump index 


loop get _pass sget another character 
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Read Keyboard (Function 08H) 


Call 
AH = 08H 


Return 


Character from keyboard 


Function 08H waits for a character to be read from standard 
input, then returns it in AL. If Control-C is pressed, 


Interrupt 23H is executed. This 


function does not echo’ the 


character. (For a keyboard input function that echoes the 
character or checks for Control-C, see Function 01H.) 


Macro Definition: read_kbd macro 


mov ah,08H 
int 21H 
endm 


Example 


The following program prompts for a password (8 characters 
maximum) and places the characters into a string without 


echoing them. 


password db 8 dup(?) 
prompt db "Password: $" 


begin: display prompt 
mov cx,8 
xor bx,bx 
get pass: read_kbd 
cmp al,0DH 
je return | 
mov password[bx],al 
inc bx 
loop get_pass 


see Function 09H 

;for explanation of $ 
:see Function 09H 
smaximum length of password 
7>BL can be an index 
sTHIS FUNCTION 

swas it a CR? 

syes, all done 

zno, put char. in string 
;bump index 

s;get another character 


Pie 
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Display String (Function 09H) 
am: Call 
AH = 09H 
DS: DX 
Pointer to string to be displayed 


BX: 
CX: 
Dx: 


None 


pe 
| 
a 


Function 09H sends to standard output a String that ends 
with "S$" (the $ is not displayed). DX must contain the 
offset (from the segment address in DS) of the string. 


Macro Definition: display macro string 
MOV dx,offset string 
mov ah,09H 
int 21H 
endm 


Example 


The following program displays the hexadecimal code of the 
key that is typed. 


table db "0123456789ABCDEF" 
result db " —- 0O0H",ODH,OAH,"S$" +:see text for 
7explanation of §$ 
begin: read_kbd_and_echo ;see Function 01H 
xOr ah,ah ;clear upper byte 
convert ax,16,result[3] ;see end of chapter 
display result *THIS FUNCTION 


jmp begin :do it again 
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Buffered Keyboard Input (Function OAH) 


Call 
AH = OAH 
DS :DX 
Pointer to input buffer 


Return 
None 


Function OAH gets a String from standard input. DX must 


contain the offset (from the segment address in DS) of an 
input buffer of the following form: 


Byte Contents 


1 Maximum number of characters in buffer, including 
the carriage return (you must set this value). 

2 Actual number of characters typed, not counting 
the Carriage Return (the function sets this 
value). 


3-n Buffer; must be at least as long as the number 
in byte l. 


Characters are read from standard input and placed in the 
buffer beginning at the third byte until a Return (0ODH) is 
read. If the buffer fills to one less than the maximum, 
additional characters read are ignored and 07H (Bel) is sent 
to standard output until a Return is read. If the string is 
typed at the console, it can be edited as it is being 
entered. If Control-C is typed, Interrupt 23H is issued. 


MS-DOS sets the second byte of the buffer to the number of 
characters read (not counting the Carriage Return). 
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Macro Definition: get string macro limit,string 


Example 


mov dx,offset string 
MOv String,limit 

mov ah,0OAH 

int 21H 

endm 


The following program gets a 16-byte (maximum) string from 
the keyboard and fills a 24-line by 80-character screen with 


it. 

buffer 
max_length 

chars entered 
string 
strings per line 
crlf 


begin: 


display screen: 


display line: 


label byte 

db ? ;maximum length 

db ? smumber of chars. 

db 17 dup (?) 716 chars + CR 

dw 0 show many strings 
sfit on line 

db ODH , OAH 


get string 17,buffer *THIS FUNCTION 

xOr bx,bx 7;So byte can be 
;used as index 

mov bl,chars entered ;get string length 


mov buffer[bx+2],"$"  ;see Function 09H 

mov al,50H ;columns per line 

cbw 

div chars entered stimes string fits 
7 on line 

xOr ah,ah clear remainder 

mov strings per line,ax ;save col. counter 

mov cx,24 erow counter 

push cx ;save it 

mov cx,Strings per line ;get col. counter 

display string ;see Function 09H 

loop display line 

display crlf ssee Function 09H 

pop cx sget line counter 


loop display screen ;display 1 more line 
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Check Keyboard Status (Function OBH) 


BX: AH = OBH 
CX: 
Dx: 
Return 
| AL 
eee FFH = characters in type-ahead 
a ae buffer 
ee eee 0 = no characters in type-ahead 
easel PHEESE 
[acs | FLAGS. | 
| ls 
pss 
| es 


Function OBH checks whether characters are available from 
standard input (if standard input has not been redirected, 
the type-ahead buffer). If characters are available, AL 
returns FFH; if not, AL returns 0. If Control-C is in the 
buffer, Interrupt 23H is executed. 


Macro Definition: check kbd status macro 
mov ah,OBH 
int 21H 
endm 
Example 


The following program continuously displays the time until 
any key is pressed. 


time db "00:00:00.00",0DH,0AH,"S" 

begin: get time ;see Function 2CH 
byte to dec ch,time ;see end of chapter 
byte to dec cl,time[3] ;see end of chapter 
byte to dec dh,time[6] ;see end of chapter 
byte to dec dl,time[9] ;see end of chapter 
display time ;see Function 09H 
check_kbd_status ;THIS FUNCTION 
cmp al,OFFH shas a key been typed? 
je return ;yes, go home 
jmp begin 7no, keep displaying 


etime 
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Flush Buffer, Read Keyboard (Function OCH) 
go Call 

AH = OCH 

AL 
1, 6, 7, 8, Or OAH = the 
corresponding function 
is called. 
Any other value = no 
further processing. 


BX: 
CX: 
DX: f 


procs [Taacs | Return 


AL 
0 = Type-ahead buffer was 
| ls flushed; no other 
| ss processing performed. 
| eS 


Function OCH empties the standard input buffer (if standard 
input has not been redirected, Function OCH empties the 
type-ahead buffer). Further processing depends on the value 
in AL when the function is called. 


1, 6, 7, 8, Or OAH -- The corresponding MS-DOS function 
is executed. 


Any other value -- No further processing; AL returns 0. 


Macro Definition: flush and read kbd macro switch 
OO a MOV al,switch 
mov ah,0OCH 
int 21H 
endm 


Example 


The following program both displays and prints characters as 
they are typed. If Return is pressed, the program sends 
Carriage Return-Line Feed to both the display and _ the 
printer. 


begin: flush _and_read kbd 1 ;THIS FUNCTION 
print char al ;see Function 05H 
cmp al,0ODH sis it a CR? 
jne begin sno, print it 
print char OAH 7see Function 05H 
display char OAH ;see Function 02H 


jmp begin ;get another character 
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Reset Disk (Function ODH) 
Call 
AH = ODH 


Return 
None 


Function ODH flushes all file buffers to ensure that the 
internal buffer cache matches the disks in the drives. It 
writes out buffers that have been modified, and marks all 
buffers in the internal cache as free. This function 
request is normally used to force a known state of the 
system; Control-C interrupt handlers should call this 
function. 


This function request does not update directory entries; | 
you must close files that have changed to update their | 
directory entries (see Function 10H, Close File). 


Macro Definition: reset disk macro 
mov ah,0ODH 
int 21H 
endm 


Example 


The following program flushes all file buffers and _ selects 
disk A. 


begin: reset disk 
select_disk "A" 


SYSTEM CALLS Function OEH Page 1-65 


Select Disk (Function OEFH) 
AX: Call 
AH = OEH 
DL 
Drive number 
(0 = A, 1 = B, etc.) 


BX: 
CX: 
DX: 


Return 
AL 
Number of logical drives 


Function OEH selects the drive specified in DL (0=A, 1=B, 


etc.) as the current drive. AL returns the number of 
drives. 


Note 


For future compatibility, treat the value returned in 


AL with care. For example, if AL returns 5, it is not 
safe to assume drives A, B, C, D, and E are all valid 
drive designators. 


SYSTEM CALLS Function OEH 


Macro Definition: select disk macro disk 


mov d1,disk [-64] 
mov ah, 0EH 

int 21H 

endm 


Example 


The following program selects the drive not 
selected in a 2-drive system. 


begin: current disk ;see Function 19H 
cmp al,00H :drive A: selected? 
je select b syes, select B 
select disk "A" ;THIS FUNCTION 
jmp return 


select _b: select disk "B" ;THIS FUNCTION 
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currently 
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Open File (Function OFH#H) 


AX: Call 

Bx: AH = OFH 

Cx: DS : DX 

Dx: Pointer to unopened FCB 
ae 
ae a Return 
ie eee) AL 
a as 0 = Directory entry found 
Te. FFH = No directory entry found 
Passe | ras 
ae ae 
a ae 
ae 


Function OFH opens a file. DX must contain the offset (from 
the segment address in DS) of an unopened File Control Block 
(FCB). The disk directory is searched for the named file. 


If a directory entry for the file is found, AL returns 0 and 
the FCB is filled as follows: 


If the drive code was 0 (current drive), it is changed 
to the actual drive used (l1=A, 2=B, etc.). This lets 
you change the current drive without interfering with 
subsequent operations on this file. 


Current Block (offset OCH) is set to 0. 


Record Size (offset OFH) is set to the system default 
of 128. 


File Size (offset 10H), Date of Last Write (offset 
14H), and Time of Last Write (offset 16H) are set from 
the directory entry. 


Before performing a sequential disk operation on the file, 
you must set the Current Record field (offset 20H). Before 
performing a random disk operation on the file, you must set 
the Relative Record field (offset 21H). If the default 
record size (128 bytes) is not correct, set it to the 
correct length. 


If a directory entry for the file is not found, or if the 
file has the hidden or system attribute, AL returns FFH. 
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Macro Definition: open macro fcb 
MOV dx,offset fcb 
mov ah ,OFH 
int 21H 
endm 


Example 


The following program prints the file named TEXTFILE.ASC 
that is on the disk in drive B. If a partial record is in 
the buffer at end-of-file, the routine that prints’ the 
partial retord prints characters until it encounters an 
end-of-file mark (ASCII 26, or Control-Z). 


fcb db 2,"TEXTFILEASC" 
db 26 dup (?) 
buffer db 128 dup (?). 
begin: set dta buffer ;see Function 1AH 
open fcb ;THIS FUNCTION 
read line: read_ seq fcb 7see Function 14H 
cmp al,02H send of file? 
je all_ done syes, go home 
cmp al,00H ;more to come? 
9 check more sno, check for partial 
rrecord 
MOV cx,80H ;yes, print the buffer 
xOr si,si :set index to 0 
print_it: print char buffer[si] ;see Function 05H 
inc si ;bump index 
loop print_it sprint next character 
jmp read line sread another record 
check_more: cmp al ,03H spart. record to print? 
jne all_done 7no 
mov cx, 80H syes, print it 
xOr Si,Si -set index to 0 
find eof: cmp buffer [si] ,26 send-of-file mark? 
je all done syes 
print char buffer[si] ;see Function 05H 
inc si ;bump index to next 
;Ccharacter 
loop find eof 
all_done: close fcb — ;see Function 10H 


OS 


en 
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Close File (Function 10H) 
AX: Call 
AH = 10H 
DS : DX 
Pointer to opened FCB 


BX: 
Cx: 
DX: 


0 = Directory entry found 
FFH = No directory entry found 


Function 10H closes a file. DX must contain the offset (to 
the segment address in DS) of an opened FCB. The disk 
directory is searched for the file named in the FCB. If a 
directory entry for the file is found, the location of the 
file is compared with the corresponding entries in the FCB. 
The directory entry is updated, if necessary, to match the 
FCB, and AL returns 0. 


This function must be called after a file is changed to 
update the directory entry. It is strongly advised that any 
FCB (even one for a file that hasn't been changed) be closed 
when access to the file is no longer needed. 


If a directory entry for the file is not found, AL returns 
FFH. 


Macro Definition: close macro fcb 
MOv dx,offset fcb 
mov ah, 10H 
int 21H 
endm 
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Example 


The following program checks the first byte of the file 
named MOD1.BAS in drive B to see if it is FFH, and prints a 
message if it is. 


message db "Not saved in ASCII format",0ODH,OAH,"S" 
fch db 2,"MOD1 BAS" 
db 26 dup (?) 
buffer db 128 dup (?) 
0 
begin: set_dta buffer ;see Function I1AH 
open fcb ;see Function OFH 
read_ seq fcb ;see Function 14H 
cmp buffer ,0FFH sis first byte FFH? 
jne all done ;no 
display message ;see Function 09H 
all_ done: close fcb THIS FUNCTION 
F 
\ 


P< 
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Search for First Entry (Function 11H) 
AX: Call 
AH = 11H 
DS : DX 
Pointer to unopened FCB 


BX: 
CX: 
DX: 


Return 
AL 
0 = Directory entry found 
FFH = No directory entry found 


Function 11H searches the disk directory for the first 
matching filename. DX must contain the offset (from the 
segment address in DS) of an unopened FCB. The filename in 
the FCB can include wildcard characters. To search for 
hidden or system files, DX must point to the first byte of 
an extended FCB prefix. 


If a directory entry for the filename in the FCB is not 
found, AL returns FFH. 


If a directory entry for the filename in the FCB is’ found, 
AL returns 0 and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address as 
follows: 


If the search FCB was normal, the first byte at the Disk 
Transfer Address is set to the drive number used (l1=A, 2=B, 
etc.) and the next 32 bytes contain the directory entry. 


If the search FCB was extended, the first byte at the Disk 
Transfer Address is set to FFH, the next 5 bytes are set to 
OOH, and the following byte is set to the value of the 
attribute byte in the search FCB. The remaining 33 bytes 
are the same as the result of the normal FCB (drive number 
and 32 bytes of directory entry). 


If Function 12H (Search for Next Entry) is used to continue 
searching for matching filenames, the original FCB at DS:DX 
must not be altered or opened. 
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The attribute field is the last byte of the extended FCB 
fields that precede the FCB (see "Extended FCB" in Section 
1.8.1 File Control Block (FFCB)). If the attribute field is 
zero, Only normal file entries are searched. Directory 
entries for hidden files, system files, volume label, and 
subdirectories are not searched. 


If the attribute field is hidden file, system file, or 
directory entry (02H, 04H, or 10H), or any combination of 
those values, all normal file entries are also searched. To 
search all directory entries except the volume label, set 
the attribute byte to 16H (hidden file and system file and 
directory entry). 


If the attribute field is volume label (08H), only the 
volume label entry is searched. 


Macro Definition: search first macro fcb 


mov dx,offset fcb 
mov ah,11H 

int 21H 

endm 


Example 


The following program verifies the existence of a file named 
REPORT.ASM on the disk in drive B. 


yes db "FILE EXISTS.$" 

no db "FILE DOES NOT EXIST.$" 

crlf db ODH,OAH,"$" 

fcb db 2,"REPORT ASM" 
db 26 dup (?) 

buffer db 128 dup (?) 

begin: set dta buffer ;see Function l1AH 
search first fcb :;THIS FUNCTION 
cmp § al1,0FFH sdirectory entry found? 
je not_there 7no 
display yes ;see Function 09H 
jmp continue 

not there: display no ;see Function 09H 


continue: display crlf ;see Function 09H 
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Search for Next Entry (Function 12H) 
os Call 
AH = 12H 
DS :DX 
Pointer to unopened FCB 


BX: 
CX: 
DX: 


0 = Directory entry found 
FFH = No directory entry found 


Function 12H is used after Function 11H (Search for First 
Entry) to find additional directory entries that match a 
filename that contains wildcard characters. It searches the 
disk directory for the next matching name. DX must contain 
the offset (from the segment address in DS) of an FCB 
previously specified in a call to Function 11H. To search 
for hidden or system files, DX must point to the first byte 
of an extended FCB prefix that includes the appropriate 
attribute value. 


If a directory entry for the filename in the FCB is not 
found, AL returns FFH. 


If a directory entry for the filename in the FCB is’ found, 
AL returns 0 and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address’ (see 
Function 11H for a description of how the unopened FCB is 
formed). 


Macro Definition: search next macro fcb 
a mMOv dx,offset fcb 
mov ah,12H 
int 21H 
endm 
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Example 


The following program displays the number of files on the 
disk in drive B. 


message db "No files",0DH,OAH,"S" 
files db 0 
fcb db 2,°22222222222" 
db 26 dup (?) 
buffer db 128 dup (?) 
begin: set dta buffer ;see Function 1AH 
search first fcb ;see Function 11H 
cmp al,OFFH ;directory entry found? 
je all_done ;no, no files on disk 
inc files ;yes, increment file 
;counter 
search dir: search next fcb ;THIS FUNCTION 
cmp al,0OFFH ;directory entry found? 
je done ;no 
inc files syes, increment file 
;counter 
jmp search dir ;check again 
done: convert files,10,message ;see end of chapter 


all _ done: display message ;see Function 09H 
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Delete File (Function 13H) 


Call 
AH = 13H 
DS :DX 
Pointer to unopened FCB 


0 = Directory entry found 
FFH = No directory entry found 


Function 13H deletes a file. DX must contain the offset 
(from the segment address in DS) of an unopened FCB. The 
directory is searched for a matching filename. The filename 
in the FCB can contain wildcard characters. 


If no matching directory entry is found, AL returns FFH. 

If a matching directory entry is found, AL returns 0 and the 
entry is deleted from the directory. If a wildcard 
character is used in the filename, all files which match 
will be deleted. 


Do not delete open files. 


Macro Definition: delete macro fcb 


MOv dx,offset fcb 
mov ah,13H 
int 21H 


endm 
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Example 


The following program deietes each file on the disk in drive 
B that was last written before December 31, 1982. 


year dw 1982 

month db 12 

day db 31 

files db 0 

message db "NO FILES DELETED.",0DH,0AH,"S" 

fcb db 2222222222722" 
db 26 dup (?) 

buffer db 128 dup (?) 

begin: set_dta buffer ;see Function 1AH 
search first fcb ;see Function 11H 
cmp al,OFFH ;directory entry found? 
jne compare s;yes 
jmp all done sno, no files on disk 

compare convert date buffer ;see end of chapter 
cmp cx,year snext several lines 
jg next ;check date in directory 
cmp dl1,month sentry against date 
9 next sabove & check next file 
cmp dh,day ;if date in directory 
jge next sentry isn't earlier. 
delete buffer sTHIS FUNCTION 
inc files sbump deleted-files 

scounter 

next: search next fcb ;see Function 12H 
cmp al,00H ;directory entry found? 
je compare syes, check date 
cmp files,0O sany files deleted? 
je all done ;no, display NO FILES 

7 ;message. 


convert files,10,message ;see end of chapter 
all _ done: display message ;see Function 09H 
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Sequential Read (Function 14H) 


Call 
AH = 14H 
DS :DX 
Pointer to opened FCB 


AX: 
BX: 
CX: 
DX: 


Return 
AL 
OOH = Read completed successfully 
01H = EOF 
02H = DTA too small 
03H = EOF, partial record 


Function 14H reads a record from the specified file. DX 
must contain the offset (from the segment address in DS) of 
an opened FCB. The record pointed to by the Current’ Block 
field (offset OCH) and Current Record (offset 20H) field is 
loaded at the Disk Transfer Address, then the Current Block 
and Current Record fields are incremented. 


The length of the record is taken from the Record Size field 
(offset OEH) of the FCB. 


AL returns a code that describes the processing: 


Code Meaning 

0 Read completed successfully. 

1 End-of-file; no data in the record. 

2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read and 
padded to the record length with zeros. 


Macro Definition: read seq macro fcb 
mov dx,offset fcb 
mov ah,14H 
int 21H 
endm 
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Example 


The following program displays the file named TEXTFILE.ASC 
that is on the disk in drive B; its function is similar to 
the MS-DOS Type command. If a partial record is in the 
buffer at end of file, the routine that displays the partial 
record displays characters until it encounters an 
end-of-file mark (ASCII 1AH, or Control-Z). 


fcb db 2,"TEXTFILEASC" 
db 26 dup (?) 
buffer db 128 dup (?),"$" 
tf 
begin: set_dta buffer 7see Function 1AH 
open fcb ssee Function OFH 
read line: read seq fcb ;THIS FUNCTION 
_ cmp al,02H ;DTA too small? 
je all done 7yes 
cmp al,00H »>end-of-file? 
jg check more ;yes 
display buffer ssee Function 09H 
jmp read line ;get another record 
check more: cmp a1,03H ;partial record in buffer? 
jne all done :no, go home 
xor si,si set index to 0 
find_eof: cmp buffer[si],26 ;is character EOF? 
je all_ done syes, no more to display 
display char buffer[si] ;see Function 02H 
inc si ;bump index 
jmp find eof scheck next character 


all_done: close fcb — ;see Function 10H 


nia: 
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Sequential Write (Function 15H) 


Call 
AH = 15H 
DS: DX 
Pointer to opened FCB 


Return 

AL 
OOH = Write completed successfully 
01H = Disk full 
02H = DTA too small 


Function 15H writes a record to the specified file. DX must 
contain the offset (from the segment address in DS) of an 
opened FCB. The record pointed to by Current Block field 
(offset OCH) and Current Record field (offset 20H) is 
written from the Disk Transfer Address, then the Current 
Block and Current Record fields are incremented. 


The record size is taken from the value of the Record Size 
field (offset OEH) of the FCB. If the Record Size is less 
than a sector, the data at the Disk Transfer Address’ is 
written to an MS-DOS buffer; MS-DOS writes the buffer to 
disk when it contains a full sector of data, or the file is 
closed, or a Reset Disk system call (Function ODH) is 
issued. 


AL returns a code that describes the processing: 


Code Meaning 
0 Write completed successfully. 
1 Disk full; write canceled. 
2 Not enough room at the Disk Transfer Address 


to write one record; write canceled. 
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Macro Definition: write seq macro fcb 
mov dx,offset fcb 
MOV ah,15H 
int 21H 
endm 
Example 


The following program creates a file named DIR.TMP on the 
disk in drive B- that contains the disk number (0=A, 1=B, 
etc.) and filename from each directory entry on the disk. 


record size equ OEH ;0ffset of Record Size 
: field in FCB 
fcbl db 2,"DIR TMP" 
db 26 dup (?) 
fcb2 db 2722222222227?" 
db 26 dup (?) 
buffer db 128 dup (?) 
begin: set dta buffer ;see Function 1AH 
search first fcb2 ;see Function 11H 
cmp al,OFFH ;directory entry found? 
je all _ done 7no, no files on disk 
create fcbl ;see Function 16H 
mov fcbl[record size],12 
;set record size to 12 
write it: write seq fcbl ;THIS FUNCTION 
= cmp al,0 swrite successful? 
jne all_done 7no, go home 
search next fcb2 ;see Function 12H 
cmp al,FFH ;directory entry found? 
je all done :no, go home 
jmp write it ;yes, write the record 


all_ done: close Fcbl ;see Function 10H 


HOF 
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Create File (Function 16H) 


Call 
AH = 16H 
DS :DX 
Pointer to unopened FCB 


AX: 
BX: 
Cx: 
DX: 


Return 
AL 
OOH = Empty directory found 
FFH = No empty directory 
available 


Function 16H creates a file. DX must contain the offset 
(from the segment address in DS) of an unopened FCB. MS-DOS 
searches the directory for an entry that matches’ the 
specified filename or, if there is no matching entry, an 
empty entry. 


If MS-DOS finds a matching entry, it opens the file and sets 
the length to zero (in other words, if you try to create a 
file that already exists, MS-DOS erases it and creates a 
new, empty file). If MS-DOS doesn't find a matching entry 
but does find an empty directory entry, it opens the file 
and sets its length to zero. In either case, the file is 
created and AL returns 0. If MS-DOS doesn't find a matching 
entry and there is no empty entry, the file is not created 
and AL returns FFH. 


You can aSSign an attribute to the file by using an extended 
FCB with the attribute byte set to the appropriate value 
(see "Extended FCB" in Section 1.8.1). 


Macro Definition: create macro fcb 
mov dx,offset fcb 
mov ah,16H 
int 21H 
endm 
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Example 


The following program creates a file named DIR.TMP on the 
disk in drive B that contains the disk number (0 = A, 1=B, 
etc.) and filename from each directory entry on the disk. 


record size equ 0OEH ;O0ffset of Record Size 
: field of FCB 
febl db 2,"DIR TMP" 
db 26 dup (?) 
fcb2 db 2722222227272" 
db 26 dup (?) 
buffer db 128 dup (?) 
begin: set dta buffer see Function l1AH 
search first fcb2 see Function 11H 
cmp al,OFFH ;directory entry found? 
je all done sno, no files on disk 
create fcbl THIS FUNCTION 
mov fcbl[record size] ,12 
“set record size to 12 
write it: write seq fcbl -see Function 15H 
- cmp al,0 swrite successful 
jne all done -no, go home 
search next fcb2 ;see Function 12H 
cmp al,FFH ;directory entry found? 
je all _ done 7no, go home 
jmp write it syes, write the record 


all_ done: close fcbl :;see Function 10H 
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Rename File (Function 178) 


Call 
AH = 17H 
DS :DX 
Pointer to modified FCB 


AX: 
BX: 
CX: 
DX: 


Return 

AL 
OOH = Directory entry found 
FFH = No directory entry 
found or destination already 
exists 


Function 17H changes the name of an existing file. DX must 
contain the offset (from the segment address in DS) of an 
FCB with the drive number and filename filled in, followed 
by a second filename at offset 11H. DOS searches the disk 
directory for an entry that matches the first filename, 
which can contain wildcard characters. 


Tf MS-DOS finds a matching directory entry and there is no 
directory entry that matches the second filename, it changes 
the filename in the directory entry to match the second 
filename in the modified FCB and AL returns zero. If a 
wildcard character is used in the second filename, the 
corresponding characters in the filename of the directory 
entry are not changed. 


This function request cannot be used to rename aie hidden 
file, a system file, or a subdirectory. If MS-DOS does not 
find a matching directory entry or finds an entry for’ the 
second filename, AL returns FFH. 


Macro Definition: rename macro fcb,newname 
Mov dx,offset fcb 
Mov ah,17H 
int 21H 
endm 


SYSTEM CALLS 


Example 


The following program prompts for the name of 


new name, 


fcb 
promptl 
prompt2 
reply 
crlf 


begin: 


Function 17H 


then renames the file. 


db 37 dup (?) 
db "Filename: $" 
db "New name: $" 
db 15 dup(?) 

db ODH,OAH,"$" 


display promptl ;see 
get_string 15,reply ;see 
display crif ;see 
parse reply[2],fcb ;see 
display prompt2 ;see 
get_string 15,reply ;see 
display crlf ;see 
parse reply [2],fcb[16] 
7see 


rename fEcb 
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a file 


Function 
Function 
Function 
Function 
Function 
Function 
Function 


Function 


;THIS FUNCTION 


and 


09H 
OAH 
09H 
29H 
09H 
OAH 
09H 


29H 


a 
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Get Current Disk (Function 19H) 
AX: Call 
BX: AH = 19H 
CX: 
DX: 
Return 
AL 
Currently selected drive 
(0 = A, 1 = B, etc.) 


Function 19H returns the current drive in AL (0O=A, I1=B, 
etc.). 


Macro Definition: current disk macro 


mov ah, 19H 
int 21H 
endm 


Example 


The following program displays the currently selected 
(default) drive in a 2-drive system. 


message db "Current disk is $" 

crlf db ODH,OAH,"S" 

begin: display message ssee Function 09H 
current disk THIS FUNCTION 
cmp ~ al,00H sis it disk A? 
jne disk _b sno, it's disk B: 
display char "A" ssee Function 02H 
jmp ~ all done 

disk b: display char "B" ssee Function 02H 


all done: display crlf ssee Function 09H 
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Set Disk Transfer Address (Function 1AH) 


Call 

AH = 1AH 

DS :DX 

Disk Transfer Address 


Return 
None 


Function lAH sets the Disk Transfer Address. DX must 
contain the offset (from the segment address in DS) of the 
Disk Transfer Address. Disk transfers cannot wrap around 


from the end of the segment to the beginning, nor can they 
overflow into another segment. 


If you do not set the Disk Transfer Address, MS-DOS defaults 
to offset 80H in the Program Segment Prefix. You can check 
the current Disk Transfer Address with Function 2FH (Get 
Data Transfer Address). 


Macro Definition: set_dta macro buffer 
mov dx,offset buffer 
mov ah, 1AH 
int 21H 
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Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A=1, B=2, etc.), then 
reads and displays the corresponding record from a file 
named ALPHABET.DAT on the disk in drive B. The file 
contains 26 records; each record is 28 bytes long. 


record size equ OEH :offset of Record Size 
sfield of FCB 
relative record equ 21H ;0ffset of Relative Record 
: field of FCB 
fcb db 2," ALPHABETDAT" 
db 26 dup (?) 
buffer db 28 dup(?),"$" 
prompt db "Enter letter: $" 
crlf db ODH,OAH,"S" 
begin: set dta buffer ;THIS FUNCTION 
open Ecb :;see Function OFH 
mov fcb[record size],28 ;set record size 
get_char: display prompt ;see Function 09H 
read kbd and echo :see Function O1H 
cmp § al,ODH ;just a CR? 
je all done syes, go home 
sub al,41H sconvert ASCII 
scode to record # 
mov fcb[relative record] ,al 
;set relative record 
display crlf :see Function 09H 
read_ran fcb :see Function 21H 
display buffer ;see Function 09H 
display crlf ;see Function 09H 
jmp get_char s:get another character 


all done: close fcb see Function 10H 
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Get Default Drive Data (Function 1BH) 


Call 
AH = 1BH 


AX: : 
BX: 
CX: 


DX: 
Return 


AL \ 
Sectors per cluster 
CX 
Bytes per sector 
DX 
Clusters per drive 
DS: BX 
Pointer to FAT ID byte 


FLAGS. 


Function 1BH retrieves data about the disk in the default 
Grive. The data is returned in the following registers: 


AL The number of sectors in acluster (allocation unit). 
CX The number of bytes in a sector. 
DX The number of clusters on the disk. 


BX returns the offset (to the Segment address in DS) of the 
first byte of the File Allocation Table (FAT), which 
identifies the type of disk in the drive: | 


Value Type of Drive 


FF Double-sided diskette, 8 sectors per track. 
FE Single-sided diskette, 8 sectors per track. 
FD Double-sided diskette, 9 sectors per track. 
FC Single-sided diskette, 9 sectors per track. 
F9 Double-sided diskette, 15 sectors per track. 
F8 Fixed disk. 


This call is similar to Function 36H (Get Disk Free Space), 
except that it returns the address of the FAT ID byte in BX 
instead of the number of available clusters, and to Function 
1CH (Get Drive Data), except that it returns data on the 
disk in the default drive instead of the disk in a specified 
drive. For a description of how MS-DOS stores data on a 
disk, including a description of the File Allocation Table, 
see Chapter 3. 
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Macro Definition: def drive data macro 


push ds 

mov ah, 1BH 

int 21H 

MOV al,byte ptr [bx] 
pop ds 

endm 


Example 


The following program displays a message that tells whether 
the default drive is a diskette or fixed disk drive. 


stdout equ 1 

msg db "Default drive is " 

remov db "diskette." 

fixed db "fixed." 

crlf db ODH ,OAH 

begin: write handle stdout,msg,17 ;display message 
jc write error ;routine not shown 
def drive data a sTHIS FUNCTION 
cmp . byte ptr [bx],0F8H ;check FAT ID byte 
jne diskette sit's a diskette 
write handle stdout, fixed,6 :see Function 40H 
jc write error :see Function 40H 
jmp short all_ done ;clean up & go home 

diskette: write handle stdout,remov,9 :see Function 40H 

all done: write handle stdout,crlf,2 -see Function 40H 


Jc write error sroutine not shown 
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Get Drive Data (Function 1CH) 


Pointer to FAT ID byte 


«Te pT] Call 
x [om [oa | = AH = 1CH 
Cx: a 
ox: [| om | «| Drive (O=default, l1=A, etc.) ( 
[| se Return 
| AL 
| OFFH if drive number is invalid, 
| otherwise sectors per cluster 
CX 
a B 
ytes per sector 
| Fuacsy | Fuacsi | DX 
Clusters per drive 
| ee 
Pe 
| eS 


Function 1CH retrieves data about the disk in the specified 
drive. DL must contain the drive number (0=default, 1=A, 
etc.). The data is returned in the following registers: 


AL The number of sectors in a cluster (allocation unit). 
CX The number of bytes in a sector. 
DX The number of clusters on the disk. 


l 
BX returns the offset (to the segment address in DS) of the ‘| 
first byte of the File Allocation Table (FAT), which 
identifies the type of disk in the drive: 


Value Type of Drive 


FF Double-sided diskette, 8 sectors per track. 
FE Single-sided diskette, 8 sectors per track. 
FD Double-sided diskette, 9 Sectors per track. 
FC Single-sided diskette, 9 sectors per track. 
F9 Double-sided diskette, 15 sectors per track. 
F8 Fixed disk. 


If the drive number in DL is invalid, AL returns OFFH. 
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This call is similar to Function 36H (Get Disk Free Space), 
except that it returns the address of the FAT ID byte in BX 
instead of the number of available clusters, and to Function 
1BH (Get Default Drive Data), except that it returns data on 
the disk in the drive specified in DL instead of the disk in 
the default drive. For a description of how MS-DOS stores 
data on a disk, including a description of the File 
Allocation Table, see Chapter 3. 


Macro Definition: drive data macro drive 


push ds 

MOV dl,drive 

mov ah, 1BH 

int 21H 

MOv al, byte ptr [bx] 
pop ds 

endm 


Example 


The following program displays a message that tells whether 
drive B is a diskette or fixed disk drive. 


stdout equ 1 

msg db "Drive B is " 

remov db "diskette." 

fixed db "fixed." 

crlf db ODH , OAH 

begin: write handle stdout,msg,11 ;display message 
jc write error ;routine not shown 
drive data 2 ;THIS FUNCTION 
cmp byte ptr [bx],0F8H ;check FAT ID byte 
jne diskette ;it's a diskette 
write handle stdout, fixed,6 ;see Function 40H 
jc write error ;routine not shown 
jmp all done ;clean up & go home 

diskette: write handle stdout,remov,9 see Function 40H 

all done: write handle stdout,crlf,2 see Function 40H 


je write error sroutine not shown 
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Random Read (Function 218) 


Call 
AH = 21H 
DS :DX 
Pointer to opened FCB 


Return 
AL 
0 = Read completed successfully 
1 = End of file, record empty 
2 = DTA too small 
3 = End of file, partial record 


Function 21H reads the record pointed to by the Relative 
Record field (offset 21H) of the FCB to the Disk Transfer 
Address. DX must contain the offset (from the segment 
address in DS) of an opened FCB. The Current Block field 
(offset OCH) and Current Record field (offset 20H) are _ set 
to agree with the Relative Record field (offset 21H), then 
the record is loaded at the Disk Transfer Address. The 


record length is taken from the Record Size field (offset 
OEH) of the FCB. 


AL returns a code that describes the processing: 


Code Meaning 
0 Read completed successfully. 
1 End-of-file; no data in the record. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read and 
padded to the record length with zeros. 


Macro Definition: read ran macro. fcb 


Mov dx,offset fcb 
Mov ah, 21H 
int 21H 


endm 


SYSTEM CALLS Function 21H Page 1-93 


Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic Sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from a file 
named ALPHABET.DAT on the disk in drive B. The file 
contains 26 records; each record is 28 bytes long. 


record size equ OEH offset of Record Size 
:field of FCB 

relative record equ 21H offset of Relative Record 

: field of FCB 

fcb db 2," ALPHABETDAT" 
db 26 dup (?) 

buffer db 28 dup(?),"$" 

prompt db "Enter letter: $" 

crlf db ODH,OAH,"S"- 

begin: set dta buffer *see Function 1AH 
open fcb ;see Function OFH 
mov fcb[record size],28 ;set record size 

get_char: display prompt ;see Function 09H 
read_kbd_and_echo ;see Function 01H 
cmp al,0ODH ;just a CR? 
je all done syes, go home 
Sub al,41H sconvert ASCII code 

;to record # 
mov Feb[relative record],al ;set relative 
;record 

display crlf 7see Function 09H 
read_ran fcb sTHIS FUNCTION 
display buffer ;see Function 09H 
display crlf ;see Function 09H 
jmp get_char ;get another char. 


all_ done: close fcb ;see Function 10H 
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Random Write (Function 22H) 


Call 
AH = 22H 
DS :DX 
Pointer to opened FCB 


Return 

AL 
OOH = Write completed successfully 
01H = Disk full 
02H = DTA too small 


Function 22H writes the record pointed to by the Relative 
Record field (offset 21H) of the FCB from the Disk Transfer 
Address. DX must contain the offset from the segment 
address in DS of an opened FCB. The Current Block (offset 
OCH) and Current Record (offset 20H) fields are set to agree 
with the Relative Record field (offset 21H), then the record 
addressed by these fields is written from the Disk Transfer 
Address. 


The record length is taken from the Record Size field 
(offset OEH) of the FCB. If the record size is less than a 
sector, the data at the Disk Transfer Address is written to 
a buffer; the buffer is written to disk when it contains a 
full sector of data, or the file is closed, or a Reset Disk 
system call (Function ODH) is issued. 


AL returns a code that describes the processing: 


Code Meaning 
0 Write completed successfully. 
1 Disk is full. 
2 Not enough room at the Disk Transfer Address 


to write one record; write canceled. 
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Macro Definition: write ran macro fcb 


Mov dx,offset fcb 
mov ah,22H 

int 21H 

endm 


Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from ae file 
named ALPHABET.DAT on the disk in drive B. After displaying 
the record, it prompts the user to enter a changed record. 
If the user types a new record, it is written to the file; 
if the user just presses Return, the record is not replaced. 
The file contains 26 records; each record is 28 bytes long. 


record size equ OEH offset of Record Size 
;field of FCB 
relative record equ 21H soffset of Relative Record 
: field of FCB 
fcb db 2," ALPHABETDAT" 
db 26 dup (?) 
buffer db 28 dup(?),0DH,0AH,"S$" 
promptl db "Enter letter: $" 
prompt2 db "New record (RETURN for no change): $" 
crlf db ODH,OAH,"S" 
reply db 28 dup (32) 
blanks db 26 dup (32) 
begin: set dta buffer see Function lAH 
open fcb :see Function OFH 
MOv fcb[record size],28 ;set record size 
get char: display promptl ;see Function 09H 
read _ kbd and_echo ;see Function 01H 
cmp al,ODH ;just a CR? 
je all done syes, go home 
Sub al,41H sconvert ASCII 
;code to record # 
mov fcb[{relative record] ,al 
= ;set relative record 
display crlf ;see Function 09H 
read ran fcb ;THIS FUNCTION 
display buffer ;see Function 09H 
display crlf ;see Function 09H 
display prompt2 ;see Function 09H 
get string 27,reply ;see Function OAH 
display crlf ;see Function 09H 
cmp reply[1],0 swas anything typed 
;besides CR? 
je get_char :no 
;get another char. 
XOLr bx,bx sto load a byte 
mov bl,reply[1] ;use reply length as 


scounter 
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all done: 


move _ string blanks,buffer,26 ;see chapter end 
move string reply[2],buffer,bx ;see chapter end 
write ran fcb THIS FUNCTION 

jmp get_char ;get another character 
close f£cb ssee Function 10H 
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Get File Size (Function 23H) 


Call 
AH = 23H 
DS :DX 
Pointer to unopened FCB 


AX: 
BX: 
CX: 
DX: 


Return 
AL 
OOH = Directory entry found 
FFH = No directory entry found 
Js 
pss 
| es 


Function 23H returns the size of the specified file. DX 
must contain the offset (from the segment address in DS) of 
an unopened FCB. 


If there is a directory entry that matches the specified 
file, MS-DOS divides the File Size field (offset 1CH) of the 
directory entry by the Record Size field (offset OEH) of the 
FCB, puts the result in the Relative Record field (offset 
21H) of the FCB, and returns 00 in AL. 


You must set the Record Size field of the FCB to the correct 
value before calling this function. If the Record Size 
field is not an even divisor of the File Size field, the 
value set in the Relative Record field is rounded up, 
yielding a value larger than the actual number of records. 


If no matching directory is found, AL returns FFH. 


Macro Definition: file size macro fcb 


mov dx,offset fcb 
mov ah, 23H 
int 21H 


endm 
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Example 


The following program prompts for the name of a file, opens 
the file to fill in the Record Size field of the FCB, issues 
a File Size system call, and displays the record length and 
number of records. 


£cb db 37 dup (?) 

prompt db "File name: $" 

msg 1 db "Record length: ",0DH,OAH,"S$" 

msg 2 db "Records: ",0DH,OAH,"$" 

crlf db ODH,O0AH,"S$" 

reply db 17 dup(?) 

begin: display prompt -;see Function 09H 
get string 17,reply -see Function OAH 
cmp — reply[1],0 :just a CR? 
jne get length sno, keep going 
mp all done syes, go home 

get length: display crlf :;see Function 09H 
parse reply[2],fcb ;see Function 29H 
open fcb esee Function OFH 
File size fcb sTHIS FUNCTION 
mov ax,word ptr fcb[33] ;get record length 
convert ax,10,msg2[9] 7see end of chapter 
mov ax,word ptr fcb[14] ; get record number 
convert ax,10,msg1[15] -see end of chapter 
display msgl ;see Function 09H 
display msg2 ;see Function 09H 


all done: close fcb ;see Function 10H 
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Set Relative Record (Function 24H) 
AX: Call 
AH = 24H 
DS :DX 
Pointer to opened FCB 


BX: 
Cx: 
DX: 


Return 


a ee None 


Fi 


Function 24H sets the Relative Record field (offset 21H) to 
the file address specified by the Current Block field 
(offset OCH) and Current Record field (offset 20H). DX must 
contain the offset (from the segment address in DS) of an 
opened FCB. You use this call to set the file pointer 
before a random read or write (Functions 21H, 22H, 27H, or 
28H). 


Macro Definition: set relative record macro. fcb 


mov dx,offset fcb 
mov ah,24H 

int 21H 

endm 


Example 


The following program copies a file using the Random Block 
Read and Random Block Write system calls. It speeds the 
copy by setting the record length equal to the file size and 
the record count to 1, and using a buffer of 32K bytes. It 
positions the file pointer by setting the Current Record 
field (offset 20H) to 1 and uSing Set Relative Record to 
make the Relative Record field (offset 21H) point to the 
same record as _ the combination of the Current Block field 
(offset OCH) and Current Record field (offset 20H). 
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current_record equ 20H ;Offset of Current Record 
| sfield of FCB 

fil_size equ 10H ;0ffset of File Size 

; field of FCB 

fcb db 37 dup (?) 

filename db 17 dup(?) 

promptl db "File to copy: $" ;see Function 09H for 

prompt 2 db "Name of copy: $" ;explanation of §$ 

crlf db ODH,0AH,"$" 

file length dw ? 

buffer db 32767 dup(?) 

begin: set dta buffer see Function 1AH 
display promptl :;see Function 09H 
get_string 15,filename -see Function OAH 
display crlf :see Function 09H 
parse filename [2] ,fcb ;see Function 29H 
open Ecb ;see Function OFH 
Mov fcb[current record],0 ;set Current Record 

sfield 
set relative record fcb sTHIS FUNCTION 
MOV ax,word ptr fcb[fil_ size] ;get file size 
Mov file length,ax ;save it for 
7 7ran_block write 
ran _block_read fcb,1,ax :see Function 27H 
display prompt2 ;see Function 09H 
get_string 15,filename :see Function OAH 
display crlf ;see Function 09H 
parse filename [2],fcb see Function 29H 
create fcb ;see Function 16H 
MOV fcb[current record],0 ;set Current Record 
sfield 
set relative record fcb ;THIS FUNCTION 
MOV — ax,file length ;get original file 
| ;-Length 

ran_block_write fcb,1,ax 7see Function 28H 


close fcb ssee Function 10H 
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Set Interrupt Vector (Function 25H) 


Call 

AH = 25H 

AL 
Interrupt number 

DS :DX 
Pointer to interrupt-handling 
routine 


AX: 
BX: 
Cx: 


DX: 


Return 
None 


Function 25H sets the address in the interrupt vector table 
for the specified interrupt. 


AL must contain the number of the interrupt. DX must 
contain the offset (to the segment address in DS) of the 
interrupt-handling routine, 


To avoid compatibility problems, programs should never’ read 
an interrupt vector directly from memory, nor set an 
interrupt vector by writing it into memory. Use Function 
35H (Get Interrupt Vector) to get a vector and this function 
request to set a vector, unless it is absolutely imperative 
that your program be compatible with pre-2.0 versions of 
MS-DOS. 


Macro Definition: 


set_vector macro interrupt,handler start 


mov al,interrupt 

mov dx,offset handler start 
mov ah,25H 

endm 


Example 


Because interrupts tend to be machine-specific, no example 
is shown. 
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Create New PSP (Function 26H) 


AX: 
BX: 
CX: 
DX: 


Segment address of new PSP 


Return 


ee 


Function 26H creates a new Program Segment Prefix. DX must 
contain the segment address where the new PSP is to -be 
created. 


This function request has been superseded. Use Function 
4BH, Code 0 (Load and Execute Program) to execute a child 
process unless it is imperative that your program be 
compatible with pre-2.0 versions of MS-DOS. 


Macro Definition: create psp macro seg addr 


MOV dx,seg addr 
mMOv ah, 26H 
endm 


Example 


Because Function 4BH, Code 0 (Load and Execute Program) and 
Code 3 (Load Overlay) have superseded this function request, 
no example is shown. 
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Random Block Read (Function 27H) 


os oe Call 
x [eo | 8 _| AH = 27H 
ox [eo [a | —§ DS:DXx 
ox: [ of | oOo | Pointer to opened FCB 
CX 
aoe ee Number of blocks to read 
Lee 
eres eee 
ieee Return 
Se 
0 = Read completed successfully 
[ Fuactn | riace. | 1 = End of file, empty record 
[csCS 2 = DTA too small 
oS” 3 = End of file, partial record 
a: 
Tes Number of blocks read 


Function 27H reads one or more records from the specified 
file to the Disk Transfer Address. DX must contain the 
offset (to the segment address in DS) of an opened FCB. CX 
must contain the number of records to read. Reading starts 
at the record specified by the Relative Record field (offset 
21H) ; you must set this field with Function 24H (Set 
Relative Record) before calling this function. 


DOS calculates the number of bytes to read by multiplying 
the value in CX by the Record Size field (offset OEH) of the 
FCB. 


CX returns the number of records read. The Current Block 
field (offset OCH), Current Record field (offset 20H), and 
Relative Record field (offset 21H) are set to address’ the 
next record. 


If you call this function with CX=0, no records are read. 
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AL returns a code that describes the processing: 


Code Meaning 
0 Read completed successfully. 
1 End-of-file; no data in the record. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read 
and padded to the record length with zeros. 


Macro Definition: 


ran_ block read macro fcb,count,rec_size 


mov dx,offset fcb 

mov cx,count 

mOV word ptr fcb[14],rec_size 
mov ah,27H 

int 21H 

endm 


Example 


The following program copies a file using the Random Block 
Read system call. It speeds the copy by specifying a record 
count of 1 and a record length equal to the file size, and 
using a buffer of 32K bytes; the file is read as a single 
record (compare to the sample program for Function 28H that 
specifies a record length of 1 and a record count equal to 
the file size). 


current record equ 20H ;offset of Current Record field 


fil size equ 10H ;offset of File Size field 

fcb db 37 dup (?) 

filename db 17 dup (?) 

promptl db "File to copy: $" ssee Function 09H for 

prompt2 db "Name of copy: $" sexplanation of §$ 

crlf db ODH,OAH,"$" 

file length dw ? 

buffer db 32767 dup (?) 

begin: set _dta buffer see Function 1AH 
display promptl ;see Function 09H 
get string 15,filename :see Function OAH 
display crlf >see Function 09H 
parse filename[2],fcb ;see Function 29H 
open fcb ssee Function OFH 
mov feb[current_record],0 ;set Current 

;Record field 

set relative record fcb ;see Function 24H 


mov ax, word ptr fcb[fil_ size] 
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;get file size 


mov file length,ax ;Save it 
ran_block_read fcb,1l,ax ;THIS FUNCTION 
display prompt2 ;see Function 09H 
get string 15,filename ;see Function OAH 
display crlf ;see Function 09H 
parse filename[2],fcb ;see Function 29H 
create fcb ;see Function 16H 
mov feb[current record] ,0;set current 
;Record field 
set relative record fcb :see Function 24H 
ran_block write fcb,1l,ax ;see Function 28H 


close fcb ssee Function 10H 
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Random Block Write (Function 28H) 


Call 

AH = 28H 

DS:DX 
Pointer to opened FCB 

CX 
Number of blocks to write 
(0 = set File Size field) 


AX: Ee 4 4 of 
BX: 
Dx: Pt 


Return 

AL 
OOH = Write completed successfully 
O1H = Disk full 
02H = End of segment 

CX 


Number of blocks written 


Function 28H writes one or more records to the specified 
file from the Disk Transfer Address. DX must contain the 
offset (to the segment address in DS) of an opened FCB; CX 
must contain either the number of records to write or 0. 


If CX is not 0, the specified number of records is written 
to the file starting at the record specified in the Relative 
Record field (offset 21H) of the FCB. If- Cx as. -0,.. no 
records are written, but MS-DOS sets the File Size field 
(offset 1CH) of the directory entry to the value in the 
Relative Record field of the FCB (offset 21H); disk 
allocation units are allocated or released, as required, to 
satisfy this new file size. 


MS-DOS calculates the number of bytes to write by 
multiplying the value in CX by the Record Size field (offset 
OEH) of the FCB. CX returns the number of records written; 
the Current Block field (offset OCH), Current Record field 
(offset 20H), and Relative Record (offset 21H) field are set 
to address the next record. 
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AL returns a code that describes the processing: 


Code Meaning 
0 Write completed successfully. 
1 Disk full. No records written. 
2 Not enough room at the Disk Transfer Address 


to write one record; write canceled. 
Macro Definition: 


ran block write macro fcb,count,rec size 


Mov dx,offset fcb > 

mov cx,count 

mov word ptr fcb[{14],rec size 
MOV ah,28H 

int 21H 

endm 


Example 


The following program copies a file using the Random Block 
Read and Random Block Write system calls. It speeds the 
copy by specifying a record count equal to the file size and 
a record length of 1, and using a buffer of 32K bytes; the 
file is copied quickly with one disk access each to read and 
write (compare to the sample program of Function 27H, that 
specifies a record count of 1 and a record length equal _ to 
file size). 


current record equ 20H ;0ffset of Current Record field 


fil size equ 10H offset of File Size field 

fcb db 37 dup (?) 

filename db 17 dup(?) 

promptl db "File to copy: $" :see Function 09H for 

prompt 2 db "Name of copy: $" ;explanation of §$ 

crlf db ODH,OAH,"S$" 

num_recs dw a 

buffer db 32767 dup(?) 

begin: set _dta buffer ssee Function 1AH 
display promptl ;see Function 09H 
get string 15,filename ;see Function OAH 
display crlf see Function 09H 
parse filename[2],fcb ;See Function 29H 
open fcb ;see Function OFH 
mov fcb[current_ record] ,0;set Current 

Record field 

set relative record fcb ;see Function 24H 
MOV ax, word ptr fcb[fil_size] 


sget file size 
mov num_recs,ax ;Save it 
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ran_ block read fcb,num_recs,1 ;THIS FUNCTION 


display prompt2 ;see Function 09H 
get_string 15,filename 7see Function OAH 
display crlf ;see Function 09H 
parse filename[2],fcb ;see Function 29H 
create fcb ;see Function 16H 
mov feb[current record],0 ;set Current 
;Record field 
set_ relative record fcb 7see Function 24H 


ran_block write fcb,num_recs,1l ;see Function 28H 
close £cb ;see Function 10H 
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Parse File Name (Function 29H) 


aie Call 
a AH = 29H 
Cx: AL 
- Controls parsing (see text) 
DS:SI 
Pointer to string to parse 
ES:DI 
Pointer to buffer for unopened FCB 
Return 
AL 
OOH = No wildcard characters 
01H = Wildcard characters used 
FFH = Drive letter invalid 
DS:SI 


Pointer to first byte past 

string that was parsed 
ES:DI 

Pointer to unopened FCB 


Function 29H parses a String for a filename of the form 
drive:filename.extension. SI must contain the offset (to 
the segment address in DS) of the string to parse; DI must 
contain the offset (to the segment address in ES) of an area 
of memory large enough to hold an unopened FCB. If the 


string contains a valid filename, a corresponding unopened 
FCB is created at ES:DI. 


AL controls the parsing. Bits 4-7 must be 0; bits 0-3 have 
the following meaning: 


Bit Value Meaning 


0 0- Stop parsing if a file Separator is 
encountered. 
1 Ignore leading separators. 
1 0 Set the drive number in the FCB to 0 


(current drive) if the string does not 
contain a drive number. 


1 Leave the drive number in the FCB unchanged 
if the string does not contain a drive 
number. 

2 0. Set the filename in the FCB to 8 blanks 


if the string does not contain a filename. 
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Bit Value Meaning 


1 Leave the filename in the FCB unchanged if 
the string does not contain a filename. 


3 l Leave the extension in the FCB unchanged 


( 


if the string does not contain an extension. \ 


0 - Set the extension in the FCB to 3 blanks 
if the string does not contain an extension. 


If the string contains a filename or extension that includes 
an asterisk (*), all remaining characters in the name or 
extension are set to question mark (?). 


Filename separators: 
2. 3 , = +/" [ ] \ < > | Space tab 


Filename terminators include all the filename separators 
plus any control character. A filename cannot contain a 
filename terminator; if one is encountered, parsing stops. 


If the string contains a valid filename: 


l. AL returns 1 if the filename or extension contains 
a wildcard character (* or ?); AL returns 0 if 
neither the filename nor extension contains a 
wildcard character. 


2. DS:SI points to the first character following the 
string that was parsed. 


ES:DI points to the first byte of the unopened FCB. 


If the drive letter is invalid, AL returns FFH. If the 


string does not contain a valid filename, ES:DI+1 points to 
a blank (20H). 


Macro Definition: parse macro string,fcb 
MOv si,offset string 
mov di,offset fcb 


push es 

push ds 

pop es 

mov al,OFH sbits 0-3 on 
mov ah,29H 

int 21H 

pop es 


endm 
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Example 


The following program verifies the existence of the file 
named in reply to the prompt. 


fcb db 37 dup (?) 

prompt db "Filename: $" 

reply db 17 dup(?) 

yes db "PILE EXISTS",ODH,OAH,"S" 

no db "FILE DOES NOT EXIST",ODH,OAH,"$" 
crlf db ODH,OAH,"S" 

begin: display prompt ssee Function 09H 
get_ string 15,reply :see Function OAH 
parse reply[2],fcb ;THIS FUNCTION 
display crlf ;see Function 09H 
search first fcb ;see Function 11H 
cmp al,OFFH sdir. entry found? 
je not_there 7;no 
display yes ;see Function 09H 
jmp return 


not there: display no 
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Get Date (Function 2AH) 


AX: 
BX: 
Cx: 
OX: 


= 

a ae 

eM ee 

pa 

er Sas Da 

y~(1=32) 

[Liacs» | riscs. | AL 
ea aes 
aa 

a ae 
Peete 


A Call 


a a 
a AH = 2AH 
a 
| 


Return 
CX 
Year (1980-2099) 
DH 
Month (1-12) 
DL 
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Day Of week (0=Sun., 6=Sat.) 


Function 2AH returns the current date set in the 
system as binary numbers in CX and DX: 


Year (1980-2099) 

Month (l=January, 2=February, etc.) 
Day (1-31) 

Day of week (0=Sunday, 1=Monday, etc.) 


Macro Definition: get date macro 


mov ah, 2AH 
int 21H 
endm 


operating 


Ps 


SYSTEM CALLS 


Example 


The following program gets the 


Function 2AH Page 1-113 


date, increments the day, 


increments the month or year, if necessary, and sets the new 


date. 
month 


begin: 


month_ok: 


db 31,28,31,30,31,30,31,31,30,31,30,31 

get date ;THIS FUNCTION 

inc dl sincrement day 

xOY bx, bx >so BL can be used as index 
mov b1l,dh smove month to index register 
dec bx smonth table starts with 0 
cmp dl,month[bx] ;past end of month? 

jle month ok 7no, set the new date 

mov dl1l,l ;yes, set day to l 

inc dh sand increment month 

cmp dh,12 ;past end of year? 

jle month_ok 7no, set the new date 

mMOv dh,l ;yes, set the month to 1 
inc cx ;increment year 


set date cx,dh,dl 


‘see Function 2AH 
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Set Date (Function 2BH) 
AX: Call 
BX: AH = 2BH 
cx: { a CX 
iy Bi Year (1980-2099) 
DMs Dk Sn 
PSs a Month (1-12) 
Pon BP DL 
eee eee Day (1-31) 
| 
a ae 
Return 
es 
ee ee OOH = Date was valid 
a eee FFH = Date was invalid 
| ss 
ee al 
Function 2BH sets the date in the operating system. 


Registers CX and DX must contain a valid date in binary: 


If the date is valid, 


the 


CX Year (1980-2099) 
DH Month (l=January, 
DL Day (1-31) 


date is not valid, 


returns FFH. 


Macro Definition: set date 


2=February, etc.) 


the date is set and AL returns 0. 


If 


the function is canceled and AL 
macro year,month,day 

MOV cx,year 

mov dh,month 

MOV dl,day 

mov ah , 2BH 

int 21H 


endm 


eS 
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Example 


The following program gets the date, increments the day, 
increments the month or year, if necessary, and sets the new 
date. 


month db 31528 731,30,31,30;7 31,4 31730;31,;30;,31 
begin: get date ssee Function 2AH 
inc dl ;increment day 
XOX bx, bx *so BL can be used as index 
MOV bl1,dh ;smove month to index register 
dec bx smonth table starts with 0 
cmp dl,month[{bx] ;past end of month? 
jle month_ok ;no, set the new date 
mov d1,l 7yes, set day to l 
inc dh sand increment month 
cmp dh,12 spast end of year? 
jle month_ok sno, set the new date 
mov dh,l ;yes, set the month to l 
inc cx increment year 


month ok: set _date cx,dh,dl ;THIS FUNCTION 
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Get Time (Function 2CH) 


Call 
AH = 2CH 


AX: 
Bx: 
CX: 
Dx: 
Return 
CH 

Hour (0-23) 
CL 

Minutes (0-59) 
DH 

Seconds (0 - 59) 
DL 

Hundredths (0-99) 


Function 2CH returns the current time set in the operating 
system as binary numbers in CX and DX: 


CH Hour (0-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 


Depending on how your hardware keeps time, some of these 
fields may be irrelevant. As an example, many CMOS clock 
chips do not resolve more than seconds. In such a case the 
value in DL will probably always be 0. 


Macro Definition: get _ time macro 
mov ah, 2CH 
int 21H 
endm 
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Example 


The following program continuously displays the time until 
any key is pressed. 


time db "00:00:00.00",0DH,"$" 
begin: get_time ;THIS FUNCTION 
byte to dec ch,time ;see end of chapter 


byte to dec cl,time[3] ;see end of chapter 
byte to dec dh,time[6] ;see end of chapter 
byte to dec dl,time[9] ;see end of chapter 


display time ;see Function 09H 
check_kbd_ status ;see Function OBH 

cmp al,OFFH shas a key been pressed? 
je return ;yes, terminate 


jmp begin 7no, display time 
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Set Time (Function 2DH) 


Call 
AH = 2DH 
CH 
Hour (0-23) 
CL 
Minutes (0-59) 
DH 
Seconds (0-59) 
DL 
Hundredths (0-99) 


AX: 
Bx: 
cx: |. 
px: 


Return 

AL 
OOH = Time was valid 
FFH = Time was invalid 


Function 2DH sets the time in the operating system. 
Registers CX and DX must contain a valid time in binary: 


CH Hour (0-23) 
CL Minutes (0-59) 


DH Seconds (0-59) 
DL Hundredths of a second (0-99) 


Depending on how your hardware keeps time, some of these 
fields may be irrelevant. As an example, many CMOS clock 
chips do not resolve more than seconds. In such a case the 
value in DL will not be relevant. 


If the time is valid, the time is set and AL returns 0. If 


the time is not valid, the function is canceled and AL 
returns FFH. 


set _ time macro hour,minutes,seconds,hundredths 


Mov ch,hour 

MOV cl,minutes 
mov dh,seconds 
mov dl,hundredths 
mov ah, 2DH 

int 21H 
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Example 


The following program sets the system clock to 0 and 
continuously displays the time. When a character is typed, 
the display freezes; when another character is typed, the 
clock is reset to 0 and the display starts again. 


time db "00:00:00.00",0DH,0AH,"$" 

begin: set_time 0,0,0,0 sTHIS FUNCTION 

read_ clock: get time ;see Function 2CH 
byte to dec ch,time see end of chapter 


byte to dec cl,time[3] ;see end of chapter 
byte to dec dh,time[6] ;see end of chapter 
byte to dec dl,time[9] ;see end of chapter 


display time ;see Function 09H 
dir console io OFFH ;see Function 06H 
cmp al,0O0OH ;was a char. typed? 
jne stop syes, Stop the timer 
jmp read clock ;no keep timer on 
stop: read_ kbd a ssee Function 08H 


jmp begin skeep displaying time 
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Set/Reset Verify Flag (Function 2EH) 


AX: 
BX: 


Cx: 
Do not verify 


Verify 


Dx: 


Return 
None 


Function 2EH tells MS-DOS whether to verify each disk write. 
If AL is 1, verify is turned on; if AL is 0, verify is 
turned off. MS-DOS checks this flag each time it writes’ to 
a disk. 


The flag is normally off; you may wish to turn it on when 
writing critical data to disk. Because disk errors are rare 
and verification slows writing, you will probably want to 
leave it off at other times. You can check the setting with 
Function 54H (Get Verify State). — 


Macro Definition: verify macro switch 


mov al,switch 
mov ah, 2EH 
int 21H 


endm 
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Example 


The following program copies the contents of a single-sided 
disk in drive A to the disk in drive B, verifying each 
write. It uses a buffer of 32K bytes. 


on equ 1 

of f equ 0 

prompt db "Source in A, target in B",0DH,OAH 
db "Any key to start. $" 

first dw 0 

buffer db 60 dup (512 dup(?)) 60 sectors 

begin: display prompt ;see Function 09H 
read kbd ssee Function 08H 
verify on ;THIS FUNCTION 
mov cx,6 ;copy 60 sectors 

76 times 
copy: push ex save counter 


abs disk read 0,buffer,60,first ;see Int 25H 
abs disk write 1,buffer,64,first ;see Int 26H 


add first,60 :do next 60 sectors 
pop Cx ;restore counter 
loop copy ;do it again 


verify off s;THIS FUNCTION 
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Get Disk Transfer Address (Function 2FH) 


Call 
AH = 2FH 


AX: : 
BX: [- 
CX: 
Return 
ES : BX 

Pointer to Disk Transfer Address 


DX: 


Function 2FH returns the segment address of the current Disk 
Transfer Address in ES and the offset in BX. 


Macro Definition: get dta macro 
MOv ah, 2fH 
int 21H 
endm 

Example 


The following program displays the current Disk fTransfer 
Address in the form segment:offset. 


message ab "DTA -- : ",0DH,OAH,"$" 

sixteen db 10H 

temp db 2 dup (?) 

begin: get_dta *THIS FUNCTION 
mov word ptr temp,ex 7;ToO access each byte 
convert temp[1l],sixteen,message [07H] See end of 
convert temp,sixteen,message [09H] ;chapter for 
convert bh,sixteen,message [0CH] ;description 
convert bl,sixteen,message [0EH] Of CONVERT 


display message ;See Function 09H 
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Get MS-DOS Version Number (Function 30H) 


AX: Call 
ai AH = 30H 
CX: 
Bx Return 
AL 
Major version number 
AH 
Minor version number 
BH 
OEM serial number 
BL:CX 
24-bit user (serial) number 
Pee OE 
ps 
|, ss 
a. 


Function 30H returns the MS-DOS version number. AL returns 


the major version number; AH returns the minor version 
number. (For example, MS-DOS 3.0 returns 3 in AL and 0O in 
AH. ) 


If AL returns 0, the version of MS-DOS is earlier than 2.0. 


Macro Definition: get version macro 
mov ah,30H 
int 21H 
endm 


Example 


The following program displays the version of MS-DOS 


is 1.28 or greater. 


message 
ten 


begin: 


db 
db 


"MS-DOS Version . 
OAH 


get_version 

cmp al,0 

jng return 

convert al,ten,message [0FH] 
convert ah,ten,message [12H] 
display message 


if it 


",0DH,OAH,"$" 
;For CONVERT 


THIS FUNCTION 
°1.28 or later? 
:No, go home 

*See end of chapter 
:for description 
*See Function 9 
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Keep Process (Function 31H) 


Call 
AH = 31H 
AL 
Return code 
DX 
Memory size, in paragraphs 


AX: fo 
BX: 
Cx: 


Return 
None 


Function 31H makes a program remain resident after it 
terminates. It is often used to install device-specific 
interrupt handlers. Unlike Interrupt 27H (Terminate But 
Stay Resident), this function request allows more than 64K 
bytes to remain resident and does not require CS to contain 
the segment address of the Program Segment Prefix. You 
should use Function 31H to install a resident program unless 
it is absolutely imperative that your program be compatible 
with pre-2.0 versions of MS-DOS. 


DX must contain the number of paragraphs of memory required 
by the program (one paragraph = 16 bytes). AL contains an 
exit code. 


Use of this in .EXE programs requires care. The value in DX 
must be the total size to remain resident, not just the size 
of the code segment which is to remain resident. A_ typical 
error is to forget about the 100H byte program header prefix 
and give a value which is 10H in DX which is 10H too small. 


MS-DOS terminates the current process and tries to set’ the 
memory allocation to the number of paragraphs in DX. No 
other allocation blocks belonging to the _ process are 
released. 


The exit code in AL can be retrieved by the parent process 
with Function 4DH (Get Return Code of Child Process) and can 
be tested with the IF command using ERRORLEVEL. 


( 
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Macro Definition: keep process macro return_code,last byte 
mov al,return_code 
mov dx,offset last byte 
mov cl,4 
shr dx,cl 


inc dx 
mov ah,31H 
int 21H 
endm 


Example 


Because the most common use of this call is to install a 
mMachine-Sspecific routine, an example is not shown. The 
macro definition shows the calling syntax. 
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Control-C Check (Function 33H) 


ax, fa 
33H 


BX: 
Cx: 


Get state 
Set state 
AL=1) 

Off 

On 


DX: 


tou hoy fl 


f AL=0) 
= Off 
= On 


FFH = error (AL was neither O nor 1 
when call was made) 


Function 33H gets or sets the state of Control-C (or 
Control-Break for IBM compatibles) checking in MS-DOS. AL 
must contain a code that specifies the requested action: 


0 Return current state of Control-C checking in DL. 
1 Set state of Control-C checking to the value in DL. 


If AL is 0, DL returns the current state (0=off, l=on). If 
AL is 1, the value in DL specifies the state to be set 
(O=off, l=on). If AL is neither 0 nor 1, AL returns FFH and 
the state of Control-C checking is not affected. 


MS-DOS normally checks for Control-C only when carrying out 
certain function requests in the 01H through OCH group (see 
the description of specific calls for details). When 
Control-C checking .is on, MS-DOS checks for Control-C when 
carrying out any function request. For example, if 
Control-C checking is off, all disk I/O proceeds without 
interruption; if Control-C checking is on, the Control-C 
interrupt is issued at the function request that initiates 
the disk operation. 
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Note 


Programs that use Function Request 06H or 07H to read 


Control-C as data must ensure that the Control-C 
checking is off. 


Macro Definition: ctrl_c_ck macro action,state 


mov al,action 
mov dl,state 
mov ah, 33H 
int 21H 

endm 


Example 


The following program displays a message that tells whether 
Control-C checking is on or off: 


message db "Control-C checking ","$" 

on db "on","$",0DH,0AH,"$" 

off db "off","$",0DH,0AH,"S" 

begin: display message ;See Function 09H 
ctrl_c ck 0 ;THIS FUNCTION 
cmp d1,0 sIs checking off? 
jg ck_on >No 
display off ;See Function 09H 
jmp return :;Go home 


ck_on: display on ;See Function 09H 
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Get Interrupt Vector (Function 35H) 


Call 
AH = 35H 
AL 
Interrupt number 


Return 
ES :BX 
Pointer to interrupt routine 


Function 35H gets the address from the interrupt vector 
table for the specified interrupt. AL must contain the 
number of an interrupt. 


ES returns the segment address of the interrupt handler; BX 
returns the offset. 


To avoid compatibility problems, programs should never’ read 
an interrupt vector directly from memory, nor set an 
interrupt vector by writing it into memory. Use this 
function request to get a vector and Function 25H (Set 
Interrupt Vector) to set a vector, unless it is absolutely 
imperative that your program be compatible with pre-2.0 
versions of MS-DOS. 


Macro Definition: get_vector macro interrupt 


mMOv al,interrupt 
mov ah,35H 
int 21H 


endm 
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Example 


The following program displays the segment and offset 
(CS:IP) for the handler for Interrupt 25H (Absolute Disk 
Read). 


message db "Interrupt 25H -- CS:0000 IP:0000" 
db ODH,OAH,"$" 

vec seg db 2 dup (?) 

vec off db 2 dup (?) 

begin: push es ;Ssave ES 
get vector 25H ;THIS FUNCTION 
mov ax,es ;INT25H segment in AX 
pop es ;Ssave ES 
convert ax,16,message [20] s;see end of chapter 
convert bx,16,message[28] see end of chapter 


display message ;See Function 9 


SYSTEM CALLS Function 36H Page 1-130 


Get Disk Free Space (Function 36H) 


Cx: i DL 
Be geri = Drive (O0=default, l1=A, etc.) 
a ae Return 
ee AX 
y= = he OFFFFH if drive number is invalid; 
en leas = otherwise sectors per cluster 
(eee See 
res ey a Available clusters 
a. Bytes per sector 
ee eee 
a ee Clusters per drive 
| es 


Function 36H returns the number of clusters available on the 
Gdisk in the specified drive, and sufficient information to 
calculate the number of bytes available on the disk. DL 
must contain a drive number (0=default, 1=A, etc.). If the 
drive number is valid, MD-DOS returns the information in the 
following registers: 


AX Sectors per cluster 
BX Available clusters 
CX Bytes per sector 
DX Total clusters 
If the drive number is invalid, AX returns OFFFFH. 


This call supersedes Functions 1BH and I1CH in earlier 
versions of MS-DOS. 


Macro Definition: get disk space macro drive 


Mov dl,drive 
mov ah, 36H 
int 21H 


endm 
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The following program displays the space information for the 
disk in drive B. 


message 


begin: 


db " clusters on drive B.",0DH,OAH °DX 

db " clusters available.",0DH,OAH *BX 

db " sectors per cluster.",0DH,0OAH *AX 

db " bytes per sector,",O0DH,OAH,"$" ;CX 

get disk space 2 ;THIS FUNCTION 
convert ax,l10,message [55] ;see end of chapter 
convert bx, 10,message [28] ssee end of chapter 
convert cx,10,message [83] ;see end of chapter 
convert dx,10,message ;see end of chapter 


display message 


;See 


Function 09H 
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Get Country Data (Function 38H) 


AX: Call 
BX: AH = 38H 
Cx: AL 
om 0 = Current country 
1 to OFEH = Country code 
OFFH = BX contains Country code 


BX (if AL=OFFH) 

Country code 255 or higher 
DS : DX 

Pointer to 32-byte memory area 


Return 
Carry set: 
AX 
2 = Invalid country code 
Carry not set: 
BX 
Country code 


Function 38H gets the country-dependent information that MS- 
DOS uses to control the keyboard and display or sets the 
currently defined country (to set the country code, see the 
next function request description). To get the information, 
DX must contain the offset (from the segment address in DS) 
of a 32-byte memory area in which the country data is to be 
returned. AL specifies the country code: 


Value in AL Meaning 


0 Retrieve information about the country 
currently set. 


1 to OFEH Retrieve information about the country 
identified by this code. 


OFFH Retrieve information about the country 
identified by the code in BX. 


BX must contain the country code if the code is 255 or 
greater. The country code is usually the international 
telephone prefix code. 
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The country-dependent information is’ returned in the 
following form: 


Offset 

Hex Decimal Field Name Length in bytes 
00 0 Date format 2 (word) 
02 2 Currency symbol 5 (ASCIZ string) 
07 7 Thousands separator 2 (ASCIZ string) 
09 9 Decimal separator 2 (ASCIZ string) 
0B 11 Date separator 2 (ASCIZ string) 
OD 13 Time separator 2 (ASCIZ string) 
OF 15 Bit field 1 
10 16 Currency places 1 
11 17 Time format 1 
12 18 Case-map call address 4 (dword) 
16 22 Data-list separator 2 (ASCIZ string) 
18 24 RESERVED 10 
Date Format: 0 = USA (m/d/y) 

1 = Europe (d/m/y) 

2 = Japan (y/m/d) 


Bit Field: Bit 0 = 0 Currency symbol precedes amount 
1 Currency symbol follows amount 


Bit 1 = 0 No space between symbol and amount 
1 One space between symbol and amount 


All other bits are undefined. 


Time format: 0 = 12-hour clock 
1 = 24-hour clock 


Currency Places: Specifies the number of places that appear 
after the decimal point on currency amounts. 


Case-Mapping Call Address: The segment and offset of a FAR 
procedure that performs country-specific lowercase-to- 
uppercase mapping on character values from 80H to OFFH. You 
call it with the character to be mapped in AL. If there is 
an uppercase code for the character, it is returned in AL; 
if there is not, or if you call it with a value less than 
80H in AL, AL is returned unchanged. AL and the FLAGS are 
the only registers altered. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX: 


Code Meaning 


2 Invalid country code (no table for it). 
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Macro Definition: get country macro country,buffer 
local gc Ol 
MOV dx,offset buffer 
mov ax,country 
cmp ax,OFFH 
jl gc_01 
mov al,OFFh 
mov bx,country 
gc Ol: MOV ah,38h 
7 int 21H 
endm 
Example 
The following program displays the time and date in the 
format appropriate to the current country code, and the 


number 999,999 and 99/100 as a 
proper currency symbol and separators. 


currency 


amount with the 


time db " : : ",5 dup (20H),"$" 
date db " 7 / “,5 dup (20H),"$" 
number db "99929992799", 0DH,0AH,"$" 


data_area db 


32 dup (?) 


begin: get_ country 0,data_area 
get time 
byte to dec ch,time 
byte to dec cl,time[03H] 
byte to dec dh,time[06H] 
get date 
sub cx,1900 
byte to dec cl,date[06H] 
cmp word ptr data_area,0 
jne not_usa 
byte_to dec dh,date 
byte to dec dl1,date[03H] 
jmp all_ done 

not_usa: byte to dec dl,date 
byte to dec dh,date[03H] 

all done: mov al,data_area[07H] 
mov number [03H] ,al 
mov al,data_area[09H] 
mov number [07H] ,al 
display time 
display date 


display char 
display 


data_area[02H] 
number 


THIS FUNCTION 
;See Function 2CH 
;See end of chapter 
sfor description of 
;CONVERT macro 

;See Function 2AH 
;Want last 2 digits 
>See end of chapter 
sCheck country code 
sIt's not USA 

-See end of chapter 
7See end of chapter 
;Display data 

;See end of chapter 
7See end of chapter 
*Thousand separator 
sPut in NUMBER 
sDecimal separator 
;Put in AMOUNT 
7See Function 
*See Function 
;See Function 
;See Function 


09H 
09H 
02H 
09H 
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Set Country Data (Function 38H) 


AX: Call 

BX: AH = 38H 

Cx: DX = -]l (OFFFFH) 
Dx: f° AL 


Country code less than 255, or 

OFFH if the country code is in BX 
BX (if AL=0FFH) 

Country code 255 or higher 


Return 
Carry set: 
AX 
2 = Invalid country code 
Carry not set: 
No error 


Function 38H sets the country code that MS-DOS uses’ to 
control the keyboard and display, or retrieves the country- 
dependent information (to get the country data, see the 
previous function request description). To set the 
information, DX must contain OFFFFH. AL must contain the 
country code if it is less than 255, or 255 to indicate that 
the country code is in BX. If AL contains OFFH, BX must 
contain the country code. 


The country code is usually the international telephone 
prefix code. See the preceding function request description 
(Get Country Data) for a description of the.country data and 
how it is used. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 


Code Meaning 


2 Invalid country code (no table for it). 
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Macro Definition: set country macro country 
local sc 01 


MOV dx, OFFFFH 
mov ax,country 
cmp ax, OF FH 
jl sc 01 
MOV bx,country 
mov al,Offh 

sc 01: mov ah,38H 
int 21H 
endm 


Example 


The following program sets the country code to the United 
Kingdom (44). 


uk equ 44 
begin: set_country uk ;THIS FUNCTION 


jc error ;routine not shown 


SYSTEM CALLS Function 39H Page 1-137 


Create Directory (Function 39H) 


Call 
AH = 39H 
DS : DX 
Pointer to pathname 


AX: 
BX: 
CX: 
DX: 


Return 
Carry set: 
AX 
3 Path not found 
5 Access denied 
Carry not set: 
No error 


Function 39H creates a new subdirectory. DX must contain 
the offset (from the segment address in DS) of an ASCIZ 
string that specifies the pathname of the new subdirectory. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 


Code Meaning 
3 Path not found. 
5 No room in the parent directory, a file with the 


same name exists in the current directory, or 
the path specifies a device. 


Macro Definition: make dir macro path 


mov dx,offset path 
mov ah,39H 
int 21H 


endm 
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Example 


The following program adds a subdirectory named NEWDIR- to 
the root directory on the disk in drive B, changes the 
current directory to NEWDIR, changes the current directory 
back to the original directory, then deletes NEWDIR. It 
displays the current directory after each step to confirm/ 
the changes. 


old path db 
new _path db 
buffer db 


"b:\",0,63 dup (?) 
"b:\new_dir",0 

"b:\",0,63 dup (?) 
begin: See Function 47H 
Routine not shown 


get dir 2,01ld path[03H] 
jc error get 


display asciz old path 7See end of chapter 
make dir new path 7THIS FUNCTION 
je error make ;Routine not shown 


change dir new_path 


See Function 3BH 


jc error change 7Routine not shown 
get dir 2,buffer [03H] See Function 47H 
je error get ;Routine not shown 


display asciz 


buffer 


change dir old path 


*See end of chapter 
sSee Function 3BH 


je error change ;Routine not shown 
rem dir new path ;See Function 3AH 
je error rem ;Routine not shown 
get dir 2,buffer [03H] See Function 47H 
je error get ;Routine not shown 


display asciz 


buffer 


See end of chapter 
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Remove Directory (Function 3AH) 


AX: 
BX: 
Cx: 
DX: 


Call 
AH = 3AH 
DS :DX 
Pointer to pathname 


Return 
Carry set: 
AX 
3 Path not found 


5 Access denied 
16 Current directory 
Carry not set: 
No error 


Function 3AH deletes a subdirectory. DX must contain the 


offset 


(from the segment address in DS) of an ASCIZ string 


that specifies the pathname of the subdirectory to be 


deleted. 


The subdirectory must not contain any files. You cannot 


erase 


carry flag 


Code 


3 


5 


16 


current directory. If there is an error, the 


(CF) is set and the error code is returned in AX: 


Meaning 

Path not found. 

The directory isn't empty; or the path doesn't 
specify a directory, specifies the root 


directory, or is invalid. 


The path specifies the current directory. 


Macro Definition: rem_dir macro path 


MOV dx,offset path 
Mov ah , 3AH 

int 21H 

endm 


SYSTEM CALLS 


Example 


The following program adds a subdirectory 
root directory on 
current directory to NEWDIR, changes the 
back to 
displays the current directory after each 


the 


Function 3AH 


the 


disk in drive B, 
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the original directory, then deletes NEWDIR. 


the changes. 


old path 
new path 
buffer 


begin: 


db "b:\",0,63 dup (?) 
db "b:\new_dir",0 

db "b:\",0,63 dup (?) 
get dir 2,01d_ path[03H] 
jc error get 
display asciz old path 
make dir new path 

je error make 
change dir new_path 


jc 


display asciz 


change dir 
je 

rem dir 

je 

get dir 

je | 


display asciz 


error change 
2,buffer [03H] 
error get 
buffer 
old path 
error change 
new_path 
error rem 
2,buffer [03H] 
error get 
buffer 


step to 


See Function 47H 
sRoutine not shown 


;See end of chapter 


-See Function 39H 
Routine not shown 
See Function 3BH 
*Routine not shown 
See Function 47H 
sRoutine not shown 


sSee end of chapter 


See Function 3BH 
sRoutine not shown 
THIS FUNCTION 
*Routine not shown 
:See Function 47H 
sRoutine not shown 


See end of chapter 


named NEWDIR to 
changes the 
current directory 


confirm \ 
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Change Current Directory (Function 3BH) 


Call 
AH = 3BH 
DS :DX 
Pointer to pathname 


AX: 
BX: 
CX: 
DX: 


Return 
Carry set: 
AX 
3 = Path not found 
Carry not set: 
No error 


Function 3BH changes the current directory. DX must contain 
the offset (from the segment address in DS) of an ASCIZ 


string that specifies the pathname of the new current 
directory. 


The directory string is limited to 64 characters. 

If any member of the path doesn't exist, the path is not 
changed. If there is an error, the carry flag (CF) is set 
and the error code is returned in AX: 


Code Meaning 


3 The pathname either doesn't exist or specifies a 
file, not a directory. 


Macro Definition: change dir macro path 


MOV dx,offset path 
mov ah,3BH 

int 21H 

endm 


Example 


The following program adds a subdirectory named NEW DIR to 
the root directory on the disk in drive B, changes the 
current directory to NEW DIR, changes the current directory 
back to the original directory, then deletes NEW DIR. It 
displays the current directory after each step to confirm 
the changes. 


SYSTEM CALLS 


Old path db 
new path db 


buffer 


begin: 


"b:\",0,63 dup 
"b:\new dir",0 


Function 3BH 
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(?) 


db "b:\",0,63 dup (?) 


get dir 


2,0ld_path[03H] 


jc error get 


display _asciz old_path 
make dir new_path 

je error make 
change dir new path 

jc error change 
get dir 2,buffer [03H] 
je error get 


display asciz 


buffer 


change dir old path 


Jc error change 
rem dir new_path 

je error rem 
get dir 2,buffer [03H] 


je error get 


display asciz 


buffer 


:See Function 47H 
Routine not shown 
7See end of chapter 
:See Function 39H 
Routine not shown 
:THIS FUNCTION 
sRoutine not shown 
See Function 47H 
Routine not shown 
*See end of chapter 
;See Function 3BH 
sRoutine not shown 
>See Function 3AH 
sRoutine not shown 
sSee Function 47H 
sRoutine not shown 
sSee end of chapter 
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Create Handle (Function 3CH) 


Call 
AH = 3CH 
DS :DX 
Pointer to pathname 


AX: 
BX: 
CX: 
DX: 


Cx 
File attribute 


Return 
Carry set: 


3 = Path not found 
4 = Too many open files 
5 = Access denied 
Carry not set: 
AX 
Handle 


Function 3CH creates a file and assigns it the first 
available handle. DX must contain the offset (from the 
segment address in DS) of an ASCIZ string that specifies the 
pathname of the file to be created. CX must contain the 
attribute to be assigned to the file, as described under 
"File Attributes" earlier in this chapter. 


If the specified file does not exist, it is created. If the 
file does exist, it is truncated to a length of 0. The 
attribute in CX is assigned to the file and the file is 
opened for read/write. AX returns the file handle. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


3 The path is invalid. 
4 Too many open files (no handle available). 
5 Directory full, a directory with the same name 


exists, or a file with the same name exists 
with more restrictive attributes. 
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Macro Definition: create handle macro path,attrib 


mov dx,offset path 
mov cx,attrib 

mov ah, 3CH 

int 21H 

endm 


Example 


The following program creates a file named DIR.TMP on the 
disk in drive B that contains the name and extension of each 
file in the current directory. 


srch_ file db "b:*.*",0 

tmp file db "b:dir.tmp",0 

buffer db 43 dup (?) 

handle dw ? 

begin: set dta buffer ;See Function l1AH 
find first file srch file,16H ;See Function 4EH 
cmp | ax,l2H > ;Directory empty? 
je all done -Yes, go home 
create handle tmp file,0 ;THIS FUNCTION 
jc error sRoutine not shown 
mov handle,ax sSave handle 

write it: write handle handle,buffer[1EH],12 ;Function 40H 
find next_file ;See Function 4FH 
cmp ax, 12H ;Another entry? 
je all done >No, go home 
jmp write it ;Yes, write record 


all_done: close handle handle ;See Function 3EH 
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Open Handle (Function 3DH) 


Call 
AH = 3DH 
AL 


AX: FE 
BX: 
CX: 
Access code (see text) 
DS :DX 
Pointer to pathname 


Dx: |. 


Return 
Carry set: 
AX 
1 = Invalid function code 
2 = File not found 
3 = Path not found 
4 = Too many open files 
5 = Access denied 


Invalid access 
Carry not set: 
No error 


Function 3DH opens any file, including hidden and_ system 
files, for input or output. DX contains the offset (from 
the segment address in DS) of an ASCIZ string that specifies 
the pathname of the file to be opened. AL contains a code 
that specifies how the file is to be opened, described later 
under "Controlling Access to the File." 


If there is no error, AX returns the file handle. MS-DOS 
sets the read/write pointer to the first byte of the file. 


Controlling Access to the File 


The value in AL is made up of three parts that _ specify 
whether the file is to be opened for read, write, or both 
(access code); what access other processes have to the file 
(sharing mode); and whether the file is inherited by a 
child process (inherit bit). 


— Access code 
—_—— > Sharing mode 


—_——— OO _ Inherit bit 
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Inherit Bit 


The high-order bit (bit 7) specifies whether the file is 
inherited by a child process created with Function 4BH (Load 
and Execute Program). If the bit is 0, the file is 
inherited; if the bit is 1, the file is not inherited. 


Sharing Mode 


The sharing mode (bits 4-6) specifies what access, if any, 
other processes have to the open file. It can have the 
following values: 


Bits 4-6 Sharing Mode Description 


000 Compatability Any process can open the file any 
number of times with this mode. 
Fails if the file has been opened 
with any of the other sharing 
modes. 


001 Deny both Fails if the file has been opened 
in compatibility mode or for read 
Or write access, even if by the 
current process. 


010 Deny write Fails if the file has been opened 
in compatibility mode or for write 
access by any other process. 


O11 Deny read Fails if the file has been opened 
in compatibility mode or for read 
access by any other process. 


100 Deny none Fails if the file has been opened 
in compatibility mode by any other 
process. 


Access Code 


The access code (bits 0-3) specifies how the file is to be 
used. It can have the following values: 


Access 
Bits 0-3 Allowed Description 


0000 Read Fails if the file has been opened in 
deny read or deny both sharing mode. 


0002 Write Fails if the file has been opened in 
deny write or deny both sharing mode. 


0010 Both Fails if the file has been opened in 
deny read, deny write, or deny both 
Sharing mode. 
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If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX. 


Code Meaning 
1 File sharing must be loaded to specify a sharing 
mode (bits 4-6 of AL). 
2 The file specified is invalid or doesn't exist. 
3 The path specified is invalid or doesn't exist. 
4 No handles are available in the current process 


or the internal system tables are full. 


5 The program attempted to open a directory or 
Volume-ID, Or open a read-only file for writing. 


12 The access code (bits 0-3 of AL) is not 0, 1, or 
2 


If this system call fails because of a file-sharing error, 
MS-DOS issues Interrupt 24H with error code 2 (Drive Not 
Ready). A subsequent Function 59H (Get Extended Error) 
returns the extended error code that specifies a sharing 
violation. 


When opening a file, it is important to inform MS-DOS of any 
operations other processes may perform on this file (sharing 
mode). The default (compatibility mode) denies all other 


processes access to the file. It may be OK for other 
processes to continue to read the file while your process is 
operating on it. In this case, you should specify "Deny 


Write," which inhibits writing by other processes but allows 
reading them. 


Similarly, it is important to specify what operations your 
process will perform ("“Access" mode). The default mode 
("Read/write") will cause the open request to fail if 
another process has’ the file opened with any sharing mode 
other than "Deny" mode. If you only want to read the file, 
your open will succeed unless all other processes have 
specified "Deny" mode or "Deny write". 


Macro Definition: open handle macro  path,access 
MOV dx, offset path 


Mov al, access 
mov ah, 3DH 
int 21H 


endm 
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Example 


The following program prints the file named TEXTFILE.ASC_ on 
the disk in drive B. 


file db "“b:textfile.asc",0 

buffer db ? 

handle dw ? 

begin: Oopen_handle file,0 :;THIS FUNCTION 
mov handle,ax Save handle 

read char: read_handle handle,buffer,l ;Read 1 character 
jc error read ;Routine not shown 
cmp ax,0 — sEnd of file? 
je return ;Yes, go home 
print char buffer ;See Function 05H 


jmp read char ;Read another 
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Close Handle (Function 3EH) 


AX: 
BX: 
CX: 


DX: 


Return 
Carry set: 
AX 
6 = Invalid handle 


[| = Carry not set: 
[rinasx [ Faas 


No error 


Function 3EH closes a file opened with Function 3DH (Open 
Handle) or 3CH (Create Handle). BX must contain the handle 


of the open file that is to be closed. 
If there is no error, MS-DOS closes the file and flushes all 
internal buffers. If there is an error, the carry flag (CF) 
is set and the error code is returned in AX: 

Code Meaning 

6 Handle is not open or is invalid. 


Macro Definition: close handle macro handle 


mov bx,handle 
mov ah , 3EH 
int 21H 


endm 
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Example 


The following program creates a file named DIR.TMP in the 
current directory on the disk in drive B that contains the 
filename and extension of each file in the current 
directory. 


srch file db "b:*.*",0 
tmp file db "b:dir.tmp",0 


buffer db 43 dup (?) 
handle dw 2 
’ 
begin: set dta buffer See Function l1AH 
find first file srch_file,16H ;See Function 4EH 
cmp ax,12H ;Directory empty? 
je all done ;Yes, go home 
create handle tmp _file,0 ;See Function 3CH 
jc error create *Routine not shown 
mov handle,ax ;Save handle 
write it: write handle handle,buffer[1EH],12 ;See Function 
3¢ error write ;40H 
find next file ;See Function 4FH 
cmp ax,12H ;Another entry? 
je all_ done 7;No, go home 
jmp write it :Yes, write record 
all_done: close handle handle ;See Function 3EH 


jc error close :Routine not shown 
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Read Handle (Function 3FH) 


AX: Call 
a AH = 3FH 
CX: BX 
Dx: Handle 
CX 
fee Bytes to read 
ae 2a DS :DX 
a ae Pointer to buffer 
[eee OBE 
Return 
hee = RS ol ; 
roger ees set: 
5 = Access denied 
Sa a 6 = Invalid handle 
— Se Carry not set: 
ai ee 


Bytes read 


Function 3FH reads from the file or device associated with 
the specified handle. BX must contain the handle. CX must 
contain the number of bytes to be read. DX must contain the 
offset (to the segment address in DS) of the buffer. 


If there is no error, AX returns the number of bytes read; 
if you attempt to read starting at end of file, AX returns 
QO. The number of bytes specified in CX is not necessarily 
transferred to the buffer; if you use this call to read 
from the keyboard, for example, it reads only up to the 
first CR. 


If you use this function request to read from. standard 
input, the input can be redirected. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX: 


Code Meaning 
5 Handle is not open for reading. 


6 Handle is not open or is invalid. 
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Macro Definition: read handle macro handle,buffer,bytes 


Mov bx,handle 

mov dx,offset buffer 
Mov cx,bytes 

mov ah,3FH 

int 21H 

endm 


Example 


The following program displays the file named TEXTFILE.ASC 
on the disk in drive B. 


filename db "b:\textfile.asc",0 

buffer db 129 dup (?) 

handle dw ? 

begin: open handle filename,0 ;See Function 3DH 
jc error open ;Routine not shown 
mov handle,ax Save handle 

read file: read handle buffer,file handle,128 
je error open ;Routine not shown 
cmp ax,0 sEnd of file? 
je return ;Yes, go home 
mov bx ,ax ;# of bytes read 
Mov buffer [bx],"$" sMake a string 
display buffer See Function 09H 


jmp read file ;Read more 
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Write Handle (Function 40H) 


AX: 
BX: 
CX: 
Dx: Handle 
CX 

Bytes to write 
DS: DX 


Pointer to buffer 


Return 

Carry set: 

AX 
5 = Access denied 
6 = Invalid handle 


Carry not set: 
AX 


Bytes written 


Function 40H writes to the file or device associated with 
the specified handle. BX must contain the handle. CX must 
contain the number of bytes to be written. DX must’ contain 
the offset (to the segment address in DS) of the data to be 
written. 


If there is no error, AX returns the number of bytes 
written. Be sure to check AX after writing to a disk file: 
if it contains 0, the disk is full; if its value is less 
than the number in CX when the call was made, it indicates 
an error even though the carry flag isn't set. 


If you use this function request to write to standard 
Output, the output can be redirected. If you call this 
function request with CX=0, the file size is set to the 
value of the read/write pointer. Allocation units are 
allocated or released, as required, to satisfy the new file 
size. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 


Code Meaning 
5 Handle is not open for writing. 


6 Handle is not open or is invalid. 
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Macro Definition: write handle macro 
mov 
Mov 
mov 
mov 
int 
endm 


Example 
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handle,data,bytes 
bx,handle 
dx,offset data 
cx,bytes 
ah,40H 
21H 


The following program creates a file named DIR.TMP in the 
current directory on the disk in drive B that contains the 
filename and extension of each file in the current 


*See Function lAH 


Find first file srch _file,16H ;Check directory 


;Directory empty? 

;Yes, go home 

:See Function 3CH 

sRoutine not shown 
Save handle 


Routine not shown 
7;Check directory 
sAnother entry? 
;No, go home 

-Yes, write record 
7See Function 3EH 
sRoutine not shown 


directory. 
srch_file db "bs *<** 0 
tmp file db "b:dir.tmp",0 
buffer db 43 dup (?) 
handle dw 2 
begin: set_dta buffer 
cmp ax,12H 
je return 
create handle tmp _ file,0 
je error create 
mov handle,ax 
write it: write handle handle,buffer[1EH],12 ;THIS FUNCTION 
jc error write 
Find next file 
cmp ax, 12H 
je all done 
jmp write it 
all_done: close handle handle 
je error close 
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Delete Directory Entry (Function 418) 


Call 
AH = 41H 
DS :DX 
Pointer to pathname 


AX: 
BX: 
CX: 
DX: 


Return 
Carry set: 
AX 
2 = File not found 
5 = Access denied 
Carry not set: 
No error 


sd] 
| 
aca ee 
ea hae) 
i en 
oi 

Te 
ss 
ew 


Function 41H erases a file by deleting its directory entry. 
DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the pathname of the file 
to be deleted. Wildcard characters cannot be used. 


If the file exists and is not read-only, it is deleted. If 
there is an error, the carry flag (CF) is set and the error 
code is returned in AX: 

Code Meaning 

2 Path is invalid or file doesn't exist. 

5 Path specifies a directory or read-only file. 
To delete a file with the read-only attribute, first change 
its attribute to 0O with Function 43H (Get/Set File 
Attribute). 


Macro Definition: delete entry macro. path 


mov dx,offset path 
mov ah,41H 
int 21H 


endm 


SYSTEM CALLS 


Example 


Function 41H 


Page 1-156 


The following program deletes all files on the disk in drive 


B whose date is earlier than December 31, 


year 
month 
day 
files 
ten 
message 
path 
buffer 


begin: 


compare: 


nexts 


how_mMany: 


all done: 


1981. 
db 1981 
db 12 
db 31 
db ? 
db OAH 
db "NO FILES DELETED.",0DH,0OAH,"S" 
db "ps* es, 0 
db 43 dup (?) 
set dta buffer «See Function l1AH 


select disk "B" 


See Function OEH 


find first file path,0 ;See Function 4EH 

jc all _ done 7Go home if empty 
convert date buffer See end of chapter 
cmp cx,year sAfter 1981? 

jg next -Yes, don't delete 
cmp d1l,month ;After December? 

19 next 7Yes, don't delete 
cmp dh,day 73lst or after? 

jge next -Yes, don't delete 
delete entry buffer[1lEH] ;THIS FUNCTION 

jc error delete sRoutine not shown 
inc files — sBump file counter 
find _next file ;Check directory 

jnc compare 7;Go home if done 

cmp files,0 ;Was directory empty? 
je all _ done 7Yes, go home 
convert files,ten,message ;See end of chapter 
display message ;See Function 09H 
select _disk "A" 7See Function OEH 
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Move File Pointer (Function 42H) 


AX: 
BX: 
Cx: 
on Method of moving 
BX 

Handle 
CX:DX 


Distance in bytes (offset) 


Return 
Carry set: 
AX 
1 = Invalid function 
6 = Invalid handle 
Carry not set: 
DX:AX 
New read/write pointer location 


Function 42H moves the read/write pointer of the file 
associated with the specified handle. BX must contain the 
handle. CX and DX must contain a 32-bit offset (CX contains 
the most significant byte). AL must contain a code that 
Specifies how to move the pointer: 


Code Cursor Is Moved To 
0 Beginning of file plus the offset. 
L Current pointer location plus the offset. 
2 End of file plus the offset. 


DX and AX return the new location of the read/write pointer 
(a 32-bit integer; DX contains the most significant byte). 
You can determine the length of a file by setting CX:DX_ to 
0, AL to 2, and calling this function request; DX:AX return 
the offset of the byte after the last byte in the file (size 
of the file in bytes). 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 
1 AL isn't 0, l, or 2. 


6 Handle isn't open. 
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Macro Definition: move ptr macro handle,high,low,method 


mov bx,handle 
Mov cx,high 
mov dx, low 
mov al,method 
mov ah ,42H 
int 21H 

endm 


Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic Sequence (A=1, B=2, etc.), then 
reads and displays the corresponding record from the _ file 
named ALPHABET.DAT in the current directory on the disk in 
drive B. The file contains 26 records; each record is 28 
bytes long. 


file db "b:alphabet.dat",0 
buffer db 28 dup (?),"$" 
prompt db "Enter letter: $" 
crlf db ODH,OAH,"S$" 
handle db ? 


record length dw 28 


begin: open handle file,0 See Function 3DH 
jc error open sRoutine not shown 
mov handle,ax Save handle 
get_char: display prompt ;See Function 09H 
read kbd_and_echo 7See Function 01H 
sub al,4lh Convert to sequence 
mul byte ptr record length ;Calculate offset 
move ptr handle,0,ax,0 ;THIS FUNCTION 
jc error move sRoutine not shown 
read handle handle,buffer,record length 
je error read ;ROoutine not shown 
cmp ax,0 sEnd of file? 
je return 7Yes, go home 
display crlf ;See Function 09H 
display buffer ;See Function 09H 
display crlf 7See Function 09H 


jmp get_char ;Get another character 
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Get/Set File Attributes (Function 43H) 


AX: Call 

BX: AH = 43H 

Cx: AL 

Dx: 0 = Get attributes 
1 = Set attributes 


CX (if AL=1) 

Attributes to be set 
DS :DX 

Pointer to pathname 


2 ; 


Return 

Carry set: 

AX 
1 = Invalid function 
3 = Path not found 
5 = Access denied 


Carry not set: 
CX 
Attribute byte (if AL=0) 


Function 43H gets or sets the attributes of a file. DX must 
contain the offset (from the segment address in DS) of an 
ASCIZ string that specifies the pathname of a file. AL must 
specify whether to get or set the attribute (0=get, l=set). 


If AL is 0 (get the attribute), the attribute byte is 
returned in CX. If AL is 1 (set the attribute), CX must 
contain the attributes to be set. The attributes = are 
described under "File Attributes" earlier in this chapter. 


You cannot change the volume-ID bit (08H) or the directory 
bit (10H) of the attribute byte with this function request. 


Tf there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


1 AL isn't 0 or l. 
3 Path is invalid or file doesn't exist. 
5 Attribute in CX cannot be changed (directory or 


Volume-ID). 
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Macro Definition: change attr macro path,action,attrib 


MOV dx,offset path 
mMOv al,action 

mov cx,attrib 

mov ah,43H 

int 21H 

endm 


Example 


The following program displays the attributes assigned to 
the file named REPORT.ASM in the current directory on the 
disk in drive B. 


header db 15 dup (20h) ,"Read-",0ODH, OAH 
db "Filename Only Hidden " 
db "System Volume Sub-Dir Archive" 
db ODH,0AH,0DH,0AH,"S" 
path db "bsreport.asm",3 dup (0),"$" 
attribute dw ? 
blanks db 9 dup (20h),"$" 
begin: change attr path,0,0 ;THIS FUNCTION 
je error mode ;Routine not shown 
mov attribute,cx ;Save attribute byte 
display header ;See Function 09H 
display path ;See Function 09H 
mov cx, 6 Check 6 bits (0-5) 
mov bx,1 sStart with bit 0 
chk bit: test attribute,bx ;Is the bit set? 
jz no_attr :No 
display char "xX" See Function 02H 
jmp short next bit ;Done with this bit 
no_attr: display char 20h ;See Function 02H 
next bit: display blanks See Function 09H 
shl bx,1 sMove to next bit 


loop chk bit Check it 
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IOCTL Data (Function 44H, Codes 0 and 1) 


AX: 
BX: AH = 44H 
CX: : 
Get device data 


Set device data 


DX: 


rm © 


BX 
Handle 
DX 
Device data (see text) 


Return 

Carry set: 

AX 
1 = Invalid function 
6 = Invalid handle 


Carry not set: 
DX 
Device data 


Function 44H, Codes 0 and 1 either gets or sets the data 
MS-DOS uses to control the device. AL must contain 0 to get 
the data or 1 to set it. BX must contain the handle. If AL 
is 1, DH must contain 0. 


The device data word is specified or returned in DX. If bit 
7 of the data is 1, the handle refers to a device and the 
other bits have the following meanings: 


Bit Value Meaning 


15 RESERVED. 

14 1 Device can process control strings sent 
with Function 44H, Codes 2 and 3 (IOCTL 
Control). This bit can only be read; it 
cannot be set. 

13-8 RESERVED 

End of file on input. 

Don't check for control characters. 

Check for control characters. 

RESERVED. 

Clock device. 

Null device. 

Console output device. 

Console input device. 


BPH HEHE OrO 


The control characters referred to in the description of bit 
5 are Control-C, Control-P, Control-S, and Control-Z. To 
read these characters as data, rather than having’ them 
interpreted as control characters, bit 5 must be set and 
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Control-C checking must be turned off, either with Function 
33H (Control-C Check) or the MS-DOS Break command. 


If bit 7 of DX is 0, the handle refers to a file and _ the 
other bits have the following meanings: 


Bit Value Meaning 

15-8 RESERVED 

6 0 The file has been written. 

0-5 Drive number (0=A, 1=B, etc.). 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 
1 AL is not 0 or 1, or AL is 1 but DH is not 0. 
6 The handle in BX is not open or invalid. 


Macro Definition: ioctl data macro code,handle 


Mov bx ,yhandle 
MOV al,code 
mov ah,44H 
int 21H 

endm 


Example 


The following program gets the device data for Standard 
Output and sets the bit that specifies not to check for 
control characters (bit 5), then clears the bit. 


get equ 0 
set equ di 
stdout equ 1 
begin: ioctl data get,stdout :;THIS FUNCTION 
jc error sroutine not shown 
MOV dh,0 :clear DH 
or d1,20H eset bit 5 
ioctl data set,stdout sTHIS FUNCTION 
je error sroutine not shown 


<control characters now treated as data, or "raw mode"> 


me “=O we 


ioctl data get,stdout *THIS FUNCTION 

jc error sroutine not shown 
mov dh,0 clear DH 

and d1,0ODFH sclear bit 5 

ioctl data set,stdout ;THIS FUNCTION 


<control characters now interpreted, or "cooked mode"> 


=e 6 QW 
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IOCTL Character (Function 44H, Codes 2 and 3) 


AH = 44H 


Send control data 
Receive control data 


W N) 


BX 

Handle 
CX 

Bytes to read or write 
DS:DX 

Pointer to buffer 


Return 
Carry set: 
AX 
1 = Invalid function 


6 = Invalid handle 
Carry not set: 
AX 

Bytes transferred 


Function 44H, Codes 2 and 3 send or receive control data to 
or from a character device. AL must contain 2 to send data 
or 3 to receive. BX must contain the handle of a_ character 
device, such as a printer or serial port. CX must contain 
the number of bytes to be read or written. DX must’ contain 
the offset (to the segment address in DS) of the data 
buffer. 


AX returns the number of bytes’ transferred. The device 
driver must be written to support the IOCTL interface. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


1 AL is not 2 or 3, or the device cannot perform the 
specified function. 


6 The handle in BX isn't open or doesn't exist. 
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Macro Definition: ioctl char macro 
mOv 
mov 
mMOv 
mov 
int 
endm 


Example 


code ,handle,buffer 
bx,handle 
dx,offset buffer 
al,code 

ah,44H 

21H 


Because processing of IOCTL control data depends on 
device and device driver, no example is included. 
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the 
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IOCTL Block (Function 44H, Codes 4 and 5) 


AX: Call 

Hy: AH = 44H 

Cx: AL 

px: 4 = Send control data 


5 = Receive control data 


Meee acai BL 
| we Drive number (O=default, 1=A, etc.) 
== ae Cx 
ta aa Bytes to read or write 
DS : DX 
Pointer to buffer 
Return 
Carry set: 
AX 
1 = Invalid function 


5 = Invalid drive 
Carry not set: 
AX 

Bytes transferred 


Function 44H, Codes 4 and 5 send or receive control data to 
or from a block device. AL must contain 4 to send data or 5 
to receive. BL must contain the drive number (0=default, 
1=A, etc.). CX must contain the number of bytes to be read 
Or written. DX must contain the offset (to the segment 
address in DS) of the data buffer. 


AX returns the number of bytes’ transferred. The device 
driver must be written to support the IOCTL interface. To 
determine this, use Function 44H, Code 0 to get the device 


data and test bit 14; if it is set, the driver supports 
IOCTL. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 


Code Meaning 


1 AL is not 4 or 5, or the device cannot perform the 
specified function. 


5 The number in BL iS not a valid drive number. 


SYSTEM CALLS Function 44H, Codes 4 and 5 Page 1-166 


Macro Definition: ioctl block macro code,drive,buffer 


mov b1,drive 

mov dx,offset buffer 
mov al,code 

Mov ah, 44H 

int 21H 

endm 


Example 


Because processing of IOCTL control data depends. on 
device and device driver, no example is included. 


the 
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IOCTL Status (Function 44H, Codes 6 and 7) 


AX: Call 
BX: AH = 44H 
Cx: AL 
ay 6 = Check input status 
7 = Check output status 
BX 
Handle 
Return 
Carry set: 
AX 
1 = Invalid function 
5 = Access denied 
6 = Invalid handle 
13 = Invalid data 


Carry not set: 


OOH = Not ready 
= Ready 


Function 44H, Codes 6 and 7 check whether the file or device 
associated with a handle is ready. AL must contain 6 to 
check whether the handle is ready for input or 7 to _ check 


whether the handle is ready for output. BX must contain the 
handle. 


AL returns the status: 


Meaning for Meaning for Meaning for 
Value Device Input File Output File 
00H Not ready Pointer is at EOF Ready 
OFFH Ready Ready Ready 


An output file always returns ready, even if the disk is 
full. 


If there is an error, the carry flag (CF) is Set and_ the 
error code is returned in AX: 


Code Meaning 


L AL is not 6 or 7. 
5 Access denied. 
6 The number in BX isn't a valid, Open handle. 


13 Invalid data. 
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Macro Definition: ioctl status macro code,handle 


mov bx,handle 
MOv al,code 
mov ah,44H 
int 21H 

endm 


Example \ 


The following program displays a message that tells whether 
the file associated with handle 6 is ready for input or at 
end~-of-file. 


stdout equ 1 

message db "File is " 

ready db "ready." 

at_eof db "at EOF." 

crlf db ODH , OAH 

g 

begin: write handle stdout,message,8 ;display message 
jc write error sroutine not shown 
ioctl status 6 ;THIS FUNCTION 
jc ioctl error sroutine not shown 
cmp Te ae 0 a ;check status code 
jne not eof s;file is ready 
write handle stdout,at_eof,7 ssee Function 40H 
jc write error sroutine not shown 
jmp all done ;clean up & go hom 

not eof: write handle stdout,ready,6 ssee Function 40H 

all done: write handle stdout,crlf,2 ;see Function 40H | 


je write error ;routine not shown 
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IOCTL Is Changeable (Function 44H, Code 08H) 


AX: 
AH = 44H 
AL = 08H 


BX: 
CX: 


- Drive number (O0=default, 1=A, etc.) 


Carry set: 


Invalid function 
Invalid drive 
Carry not set: 


— 
nou 


jo) 
wou 


Changeable 
Not changeable 


Function 44H, Code 08H checks whether a drive contains a 
fixed or removable disk. BL must contain the drive number 
(O=default, 1=A, etc.). AX returns 0 if the disk can _ be 
changed, 1 if it cannot. 


This call lets a program determine whether to issue a 
message to change disks. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX. 


Code Meaning 
a The device does not support this call. 
15 The number in BL is not a valid drive number. 
In the case where this call returns error 1 because’ the 
device doesn't Support the call, the caller should make the 


assumption that the driver cannot be changed. 


Macro Definition: ioctl change macro drive 


MOV bl, drive 
mov al, 08H 
mov ah, 44H 
int 21H 
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Example 


The following program checks whether the current drive 
contains a removable disk. If not, processing continues; 
if so, it prompts the user to replace the disk in the 
current drive. 


stdout equ 1 

message db "Please replace disk in drive " 

drives db "ABCD" 

crlf db ODH , OAH 

tf 

begin: ioctl change 0 ;THIS FUNCTION 
jc ioctl error ;routine not shown 
cmp ax,0 ;current drive changeable? 
jne continue zno, continue processing 
write handle stdout,message,29 ;see Function 40H 
je write error ;routine not shown 
current disk ;see Function 19H 
xor bx , bx sclear index 
mov bl,al sget current drive 


display char drives[bx] ;see Function 02H 
write handle stdout,crlf,2 ;see Function 40H 
je write error ;routine not shown 
continue: 
; (Further processing here) 
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TOCTL Is Redirected Block (Function 44H, Code 098) 


AX: Call 

BX: AH = 44H 

ys AL = 09H 
BL 


DX: 


Drive number (0=default, 1=A, etc.) 


i eee 
| Return 
Ft Carry set: 
ee ee eel AX 

1 = Invalid function code 

15 = Invalid drive number 

Carry not set: 
DX 


Device attribute bits 


Function 44H, Code 09H checks whether a drive letter refers 
to a drive on a Microsoft Networks workstation (local) or is 
redirected to a server (remote). BL must contain the drive 
number (Q=default, 1=A, etc.). 


If the block device is local, DX returns the attribute word 
from the device header. If the block device is remote, only 
bit 12 (1000h) is set; the other bits are 0 (reserved). 


An application program should not test bit 12. Applications 
should make no distinction between local and remote files or 
devices. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX: 


Code Meaning 
1 File sharing must be loaded to use this system 
call. 
15 The number in BL is not a valid drive number, 


Macro Definition: ioctl rblock macro drive 


mov bl, drive 
mov al, O9H 
mov ah, 44H 
int 21H 


endm 
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Example 
The following program checks whether drive B is’ local 


remote, and displays the appropriate message. 


stdout 


a 
message 
loc 
rem 
crl1lf 


begin: 


not_loc: 


cone: 


equ 1 

db "Drive B: is " 

db "local." 

db "remote." 

db ODH , OAH 

write handle stdout,message,12 ;display message 
je write error sroutine not shown 
ioctl _rblock 2 = ;THIS FUNCTION 

je ioctl error sroutine not shown 
test dx,1000h sbit 12 set? 

jnz not loc syes, it's remote 
write handle stdout,loc,6 :see Function 40H 
jo write error ;routine not shown 
jmp done 

write handle stdout,rem,7 ssee Function 40H 
je write error ;routine not shown 
write handle stdout,crlf,2 ssee Function 40H 
jc write error sroutine not shown 


72 


Or 
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IOCTL Is Redirected Handle (Function 44H, Code OAH) 


Return 

Carry set: 

AX 
1 Invalid function code 
6 Invalid handle 

Carry not set: 

DX 
IOCTL bit field 


Function 44H, Code OAH checks whether a handle refers to a 
file or device on a Microsoft Networks workstation (local) 
or is redirected to a server (remote). BX must contain the 
file handle. DX returns the IOCTL bit field; Bit 15 is set 
if the handle refers to a remote file or device. 


An application program should not test bit 15. Applications 
should make no distinction among local and remote files and 
devices. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


1 Network must be loaded to use this system call. 
6 The handle in BX is not a valid, open handle. 
Macro Definition: ioctl rhandle macro handle 
MOV bx, handle 
mov al, OAH 
mov ah, 44H 
int 21H 


endm 
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Example 
The following program checks whether handle 5 refers to a 
local Or remote file or device, then displays’ the 
appropriate message. 
stdout equ 1 
message db "Handle 5 is " 
loc db "local." 
rem db "remote." 
crlf db ODH , OAH 
begin: write handle stdout,message,12;display message 
jc write error sroutine not shown 
ioctl rhandle 5 ;THIS FUNCTION 
jc ioctl error sroutine not shown 
test ax,1000h sbit 12 set? 
jnz not loc ;yes, it's remote 
write handle stdout,loc,6 ssee Function 40H 
ic. write error ;routine not shown 
jmp done 
not _ loc: write handle stdout,rem,7 ssee Function 40H 
a jc write error sroutine not shown 
done: write handle stdout,crlf,2 :see Function 40H 


je write error ;routine not shown 
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IOCTL Retry (Function 44H, Code OBH) 


AX: 


44H 
OBH 


BX: 
CX: 
Dx: 
Number of retries 
CX 
Wait time 


Return 
Carry set: 
AX 
1 = Invalid function code 
Carry not set: 
No error 


Function 44H, Code OBH specifies how many times MS-DOS 
should retry a disk operation that fails because of a 
file-sharing violation. BX must contain the number. of 
retries. CX controls the pause between retries. 


MS-DOS retries a disk operation that fails because of a 
file-sharing violation three times unless this system call 
is used to specify a different number. After the specified 
number of retries, MS-DOS issues Interrupt 24 for the 
requesting process. 


The effect of the delay parameter in CX is machine-dependent 
because it specifies how many times MS-DOS should execute an 
empty loop. The actual time varies, depending on _ the 
processor and clock speed. You can determine the effect on 
your machine by using Debug to set the retries to 1 and time 
several values of CX. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX, 


Code Meaning 


1 File sharing must be loaded to use this system 
call. 
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Macro Definition: ioctl retry macro retries, wait 


mov bx, retries 
mov cx, wait 
mov al, OBH 
mov ah, 44H 

int 21H 

endm 


Example 


The following program sets the number of sharing retries' to 
10 and specifies a delay of 1000 between retries. 


begin: ioctl retry 10,1000 ;THIS FUNCTION 
jc error ;routine not shown 
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Duplicate Pile Handle (Function 45H) 


AX: 
BX: 
Cx: 


Handle 


DX: 


Return 

Carry set: 

AX 
4 = Too many open files 
6 = Invalid handle 


i oo 

ee: ee 

mae ee 

a as 

| Carr ° 
y not set: 

| FLAGSH | FLAGS. AX 

Ps 

aa aa 

Ps 


New handle 


Function 45H creates an additional handle for ae file. BX 
must contain the handle of an open file. 


MS-DOS returns the new handle in AX. The new handle refers 
to the same file as the handle in BX, with the file pointer 
at the same position. 


After this function request, moving the read/write pointer 
of either handle also moves the pointer’ for the other 
handle. This function request is usually used to redirect 
standard input (handle 0) and standard output (handle 1). 
For a description of standard input, standard output, and 
the advantages and techniques of manipulating them, see 
Software Tools by Brian W. Kernighan and P.J. Plauger 
(Addison-Wesley Publishing Co., 1976). 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 
4 Too many open files (no handle available). 
6 Handle is not open or is invalid. 


Macro Definition: xdup macro. handle 


mov bx ,handle 
Mov ah ,45H 
int 21H 


endm 
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Example 

The following program redefines standard output (handle _ 1) 
to a file named DIRFILE, invokes a second copy of 
COMMAND.COM to list the directory (which writes the 
directory to DIRFILE), then restores standard input to 
handle 1. 

pgm file db "command.com",0 

cmd line db 9,"/c dir /w",0dH 

parm blk db 14 dup (0) 

path db "dirfile",0 

dir file dw 3 ; For handle 

sav_ stdout dw  ? ; For handle 


begin: 


set block last_inst ; 
jc error setblk ; 
create handle path,0 ; 
jc error create ; 
mov dir file,ax : 
xdup 1 : 
jc error xdup ; 
mov Sav_stdout,ax ; 
xdup2 dir file,l ; 
ule error xdup2 ; 


exec 

jc error exec 
xdup2 sav_stdout,1 
jc error xdup2 


close handle sav_stdou 
je error close 
close handle dir file 
jc error close 


=e “8 “tO ct ~e =e se 


pgm_file,cmd_line,parm blk ; 


See Function 4AH 

Routine not shown 

See Function 3CH 

Routine not shown 

Save handle 

THIS FUNCTION 

Routine not shown 

Save handle 

See Function 46H 

Routine not shown 

See Function 
4BH 

Routine not shown 

See Function 46H 

Routine not shown 

: See Function 3EH 

Routine not shown 

See Function 3EH 

Routine not shown 
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Force Duplicate File Handle (Function 46H) 


AH = 46H 
BX 
Handle 
CX 
Second handle 


Return 
Carry set: 
AX 
4 = Too many open files 
6 = Invalid handle 
Carry not set: 
No error 


Function 46H forces a specified handle to refer the same 
file as another handle already associated with an open file. 
BX must contain the handle of the open. file; CX must 
contain the second handle. 


On return, the handle in CX now refers to the same file at 
the same position as the handle in BX. If the file referred 
to by the handle in CX was open at the time of the call, it 
is closed. 


After this call, moving the read/write pointer of either 
handle also moves’ the pointer for the other handle. This 
function request is normally used to redirect standard input 
(handle 0) and Standard output (handle 1). For a 
description of standard input, Standard output, and_ the 
advantages and techniques of manipulating them, see Software 
Tools by Brian W. Kernighan and Pid. Plauger 
(Addison-Wesley Publishing Co., 1976). . 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 


Code Meaning 
4 Too many open files (no handle available). 


6 Handle is not open or is invalid. 
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Macro Definition: xdup2 macro handlel,handle2 


mov bx,handlel 
Mov cx,handle2 
mov ah,46H 

int 21H 

endm 


Example 


The following program redefines standard output (handle 
to a’ file named DIRFILE, invokes a second copy 
COMMAND.COM to list the directory (which writes t 
directory to DIRFILE), then restores standard input 
handle 1. 


pgm file db "command.com" ,0 
cmd line db 9,"/c dir /w",0dH 
parm blk db 14 dup (0) 


See Function 3EH 


close handle dir file 
Routine not shown 


Jc error close 


path — db "dirfile",0 

dir file dw ? ; For handle 

sav stdout dw ? ; For handle 

begin: set_ block last_inst ; See Function 4AH 
jc error setblk ; Routine not shown 
create handle path,0 ; See Function 3CH 
jc error create ; Routine not shown 
mov dir file,ax : Save handle 
xdup 1 ; See Function 45H 
jc error xdup ; Routine not shown 
MOV sav_stdout,ax ; Save handle 
xdup2 dir file,1l : 
jc error xdup2 * Routine not shown 
exec pgm file,cmd line,parm blk ; See BUneeto 

BH 
jc error exec ; Routine not shown 
xdup2 sav stdout,l ; THIS FUNCTION 
jc error xdup2 ; Routine not shown 
close handle sav_stdout ; See Function 3EH 
jc error close : Routine not shown 
tf 
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Get Current Directory (Function 47H) 


Call 
AH = 47H 
DS:SI 
Pointer to 64-byte memory area 
DL 
Drive number 


AX: 
BX: 
Cx: 
Ox: 


Return 
Carry set: 
AX 
15 = Invalid drive number 
Carry not set: 
No error 


Function 47H returns the pathname of the current directory 
on a specified drive. DL must contain a drive number 
(O=default, 1=A, etc.). SI must contain the offset (from 
the segment address in DS) of a 64-byte memory area. 


MS-DOS places an ASCIZ string in the memory area _ that 
consists of the pathname, starting from the root directory, 
of the current directory for the drive specified in DL. The 
string does not begin with a backslash and does not include 
the drive letter. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX: 


Code Meaning 


1 


ui 


The number in DL is not a valid drive number. 


Macro Definition: get dir macro  drive,buffer 


mov dl,drive 

MOV si,offset buffer 
mov ah,47H 

int 21H 


endm 
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Example 


The following program displays the current directory on the 
disk in drive B. 


disk db "be\s" 

buffer db 64 dup (?) 

begin: get dir 2,buffer *THIS FUNCTION 
je error dir sRoutine not shown 
display disk 7See Function 09H 


display asciz buffer ;See end of chapter 
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Allocate Memory (Function 48H) 


Call 
AH = 48H 
BX 
Paragraphs of memory requested 


AX: 
BX: 
Cx: 
DX: 


7 = Memory control blocks damaged 
= Insufficient memory 
BX 

Paragraphs of memory available 
Carry not set: 
AX 

segment address of allocated memory 


Function 48H tries to allocate the specified amount of 
memory to the current process. BX must contain the number 
of paragraphs of memory (1 paragraph is 16 bytes). 


If sufficient memory is available to satisfy the request, AX 
returns the segment address of the allocated memory (the 
offset is 0). If sufficient memory is not available, BX 


returns the number of paragraphs of memory in the largest 
available block. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


7 Memory control blocks damaged (a user program 
changed memory that doesn't belong to it). 


8 Not enough free memory to satisfy the request. 


Macro Definition: allocate memory macro bytes 


mov bx,bytes 
mov c1,4 

shr bx,cl 
ine bx 

mov ah, 48H 
int 21H 


endm 
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Example 


The following program opens the file named TEXTFILE.ASC, 
calculates its size with Function 42H (Move File Pointer), 
allocates a block of memory the size of the file, reads the 
file into the allocated memory block, then frees’ the 
allocated memory. 


path db "textfile.asc",0 
msg1l db "File loaded into allocated memory block.", 
ODH , OAH 
msg2 db "Allocated memory now being freed 
(deallocated) .",0DH,0OAH 
handle dw ? 
mem seg dw ? 
file len dw fs 
begin: Open handle path,0 
je error open ;Routine not shown 
mov handle,ax sSave handle 
move ptr handle,0,0,2 ;See Function 42H 
je error move ;Routine not shown 
mov file len,ax :;Save file length 
set block last_inst See Function 4AH 
je error setblk ;Routine not shown 
allocate memory file len ;THIS FUNCTION 
je error alloc  ;Routine not shown 
mov mem seg,ax :Save address of new memory 
move ptr handle,0,0,0 ;See Function 42H 
jc error move sRoutine not shown 
push ds ;Save DS 
mov ax,mem seg Get segment of new memory 
Mov ds,ax sPoint DS at new memory 


read_ handle cs:handle,0,cs:file len ;Read file intc 
new memory 


~e 


pop ds Restore DS 

je error read ;Routine not shown 
(CODE TO PROCESS FILE GOES HERE) 

write handle stdout,msg1,42 ;See Function 40H 


=e 


je write error ;Routine not shown 
free memory mem_seg ;See Function 49H 
je error freemem ;Routine not shown 


write handle stdout,msg2,49 ;See Function 40H 
je write error ;Routine not shown 
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Free Allocated Memory (Function 498) 


AX: 
BX: 


CX: 
Segment address of memory to be 
freed 


DX: 


Return 
Carry set: 


AX 
7 Memory control blocks damaged 


a ive! 9 Incorrect segment 
[rises [ rinse: 


Carry not set: 
C No error 


Function 49H releases (makes available) a block of memory 
previously allocated with Function 48H (Allocate Memory). 
ES must contain the segment address of the memory block to 
be released. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 


Code Meaning 


7 Memory control blocks damaged (a uSer program 
changed memory that doesn't belong to it). 


9 The memory pointed to by ES was not allocated 
with Function 48H. 


Macro Definition: free memory macro seg addr 


mov ax,seg addr 
Mov es,ax 
mov ah,49H 

int 21H 


endm 
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Example 


The following program opens the file named TEXTFILE.ASC, 
calculates its size with Move File Pointer (42H), allocates 
a block of memory the size of the file, reads the file into 
the allocated memory block, then frees the allocated memory. 


path db "textfile.asc",0 
msgl db "File loaded into allocated memory block.", 
ODH , OAH 
msg2 db "Allocated memory now being freed 
(deallocated) .",0DH, OAH 
handle dw ? 
mem seg dw ? 
file len dw ? 
a 
begin: open handle path,0 
jc error open sRoutine not shown 
mov handle,ax sSave handle 
move ptr handle,0,0,2 ;See Function 42H 
je error move ;Routine not shown 
mov file len,ax :Save file length 
set block last_inst ;See Function 4AH 
je error setblk ;Routine not shown 
allocate memory file len ;See Function 48H 
jc error alloc sRoutine not shown 
MOV mem seg,ax ;Save address of new memory 
mov_ptr handle,0,0,0 ;See Function 42H 
jc error move ;Routine not shown 
push ds 7;Save DS 
Mov ax,mem_ seg 7Get segment of new memory 
Mov ds,ax :;Point DS at new memory 


read handle handle,code,file len ;Read file into 
— a new memory 

pop ds ;Restore DS 

jc error read ;Routine not shown 

(CODE TO PROCESS FILE GOES HERE) 

write handle stdout,msgl1,42 ;See Function 40H 


=e 


ba | 


jc write error sRoutine not shown 
free memory mem_seg ;THIS FUNCTION 
jc error freemem ;Routine not shown 


write handle stdout,msg2,49 ;See Function 40H 
je write error ;Routine not shown 
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Set Block (Function 4AH) 


Call 
AH = 4AH 
BX 
Paragraphs of memory 
ES 
Segment address of memory area 


Return 

Carry set: 

AX 

Memory control blocks damaged 
Insufficient memory 

Incorrect segment 


ie °) 
tou i 


BX 

Paragraphs of memory available 
Carry not set: 

No error 


Function 4AH changes the size of a memory allocation block. 
ES must contain the segment address of the memory block. BX 
must contain the new size of the memory block, in paragraphs 
(1 paragraph is 16 bytes). 


MS-DOS attempts to change the size of the memory block. If 
the call fails on a request to increase memory, BX returns 
the maximum size (in paragraphs) to which the block can be 
increased. 


Because MS-DOS allocates all of available memory to a é.COM 
program, this call is most often used to reduce the size of 
a program's initial memory allocation block. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


7 Memory control blocks destroyed (a uSer program 
changed memory that doesn't belong to it). 


8 Not enough free memory to satisfy the request. 


9 Wrong address in ES (the memory block it points 
to cannot be modified with Set Block). 
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Macro Definition: 


This macro is set up to Shrink the initial memory allocation 
block of a .COM program. It takes as a parameter the offset 
of the first byte following the last instruction of a 
program (LASTINST in the sample programs), uses it to 
calculate the number of paragraphs in the program, then adds 
17 to the result -- 1 to round up and 16 to set aside 256 
bytes for a stack. It then sets up SP and BP to point to 
this stack. 


set block macro last byte 


MOV bx,offset last byte 
Mov cl,4 7 
shr bx,cl 

add bx,17 

Mv ah, 4AH 

int 21H 

Mov ax,bx 

shl ax,cl 

dec ax 

dec ax 

mMOv sp,ax 

endm 


Example 


The following program invokes a second copy of COMMAND.COM 
and executes a Dir (directory) command. 


pgm file db "“command.com" ,0 

cmd line db 9,"/c dir /w",0DH 

parm blk db 14 dup (?) 

reg save db 10 dup (?) 

begin: set_block last_inst ;THIS FUNCTION 
exec pgm_file,cmd_line,parm_blk,0 ;See Function 


* ABH 
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Load and Execute Program (Function 4BH, Code 00H) 


ay Call 
a AH = 4BH 
= AL = 00H 
is DS : DX 
Pointer to pathname 
ES :BX 
Pointer to parameter block 
Return 
Carry set: 
AX 
1 = Invalid function 
2 = File not found 
8 = Insufficient memory 
10 = Bad environment 
11 = Bad format 


Carry not set: 
No error 


Function 4BH, Code 00H loads and executes a program. DX 
must contain the offset (from the segment address in DS) of 
an ASCIZ string that specifies the drive and pathname of an 
executable program file. BX must contain the offset (from 


the segment address in ES) of a parameter block. AL must 
contain 0. 


There must be enough free memory for MS-DOS to load _ the 
program file. All available memory is allocated to a 
program when it is loaded, so you must free some memory with 
Function 4AH (Set Block) before using this function request 
to load and execute another program. Unless memory is 
needed for some other purpose, shrink to the minimum amount 
of memory required by the current process before issuing 
this function request. 


MS-DOS creates a Program Segment Prefix for the program 
being loaded, and sets the terminate and Control-C addresses 
to the instruction that immediately follows the call _ to 
Function 4BH in the invoking program. 
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The parameter block consists of four addresses: 


Offset Length 


(Hex) (Bytes) Description 

00 2 (word) Segment address of environment to be 
passed; OOH means copy the parent's 
environment. 

02 4 (dword) Segment:Offset of command line to be 


placed at offset 80H of the new 
Program Segment Prefix. This must 
be a correctly formed command line 
no longer than 128 bytes. 


06 4 (dword) Segment:Offset of FCB to be placed 
at offset 5CH of the new Program 
Segment Prefix (the Program Segment 
Prefix is described in Chapter 4). 


OA 4 (dword) Segment:Offset of FCB to be placed 
at offset 6CH of the new Program 
Segment Prefix. 


All open files of a program are available to the newly 
loaded program, giving the parent program control over the 
definition of standard input, output, auxiliary, and printer 
devices. For example, a program could write a series of 
records to a file, open the file as standard input, open a 
second file as standard output, then use Load and Execute 
Program to load and execute a program that takes its input 


from standard input, sorts records, and writes to standard 
output. 


The loaded program also receives an environment, a series of 
ASCIZ strings of the form parameter=value (for example, 
VERIFY=ON). The environment must begin on a paragraph 
boundary, be less than 32K bytes long, and end with a byte 
of OOH (that is, the final entry consists of an ASCII string 
followed by two bytes of 00H). After the last byte of zeros 
is a set of initial arguments passed to a program that 
contains a word count followed by an ASCIZ string. If the 
file is found in the current directory, the ASCIZ string 
contains the drive and pathname of the executable program as 
passed to Function 4BH. If the file is found in the path, 
the filename is concatenated with the path information. (A 
program may use this area to determine where the program was 
loaded from.) If the word environment address is 0, the 
loaded program either inherits a copy of the parent's 


environment or receives a new environment built for it by 
the parent. 


Place the segment address of the environment at offset 2CH 
of the new Program Segment Prefix. To build an environment 
for the loaded program, put it on a paragraph boundary and 


SYSTEM CALLS Function 4BH, Code 00H Page 1-191 


place the segment address of the environment in the first 
word of the parameter block. To pass a copy of the parent's 
environment to the loaded program, put OOH in the first word 
of the parameter block. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 


Code Meaning 
i AL is not 0 or 3. 
2 Program file not found or path is invalid. 
8 Not enough memory to load the program. 

11 Program file is an .EXE file that contains 


internally inconsistent information. 
Executing Another Copy of COMMAND .COM 


Because COMMAND.COM takes care of such details as building 
pathnames, searching the command path for program files, and 
relocating .EXE files, the simplest way to load and execute 
another program is to load and execute an additional copy of 
COMMAND.COM, passing it a command line that includes the /C 
Switch -- which tells COMMAND.COM to treat the remainder of 
the command line as an executable command -- that invokes 
the .COM or .EXE file. 


This requires 17K bytes of available memory, SO a program 
that does this should be sure to shrink its initial memory 
allocation block with Function 4AH (Set Block). The format 
of a command line that contains the /C switch: 


<length>/C <command><0ODH> 


<Length> is the length of the command line, counting the length 
byte but not counting the ending carriage return (ODH). 


<Command> is any valid MS-DOS command. 
<QODH> is a carriage return character. 


If a program executes another program directly -- naming it 
as the program file to Function 4BH instead of COMMAND.COM 


-- it must perform all the processing normally done _ by 
COMMAND .COM. 


SYSTEM CALLS 


Macro Definition: 


exec 


Example 


macro 
mov 
mov 
mov 
mov 
mOv 
Mov 
mov 
mov 
mov 
mov 
int 
endm 
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path,command,parms 
dx,offset path 
bx,offset parms 


word 
word 
word 
word 
word 
word 
al,0 


ptr 
ptr 
ptr 
ptr 
ptr 
ptr 


ah, 4BH 


21H 


parms [02H] ,offset command 
parms[04H],cs 

parms [06H] ,5CH 
parms[08H],es 

parms [OAH] ,6CH 

parms [OCH] ,es 


The following program invokes a second copy of COMMAND.COM 
and executes a 


Switch: 


pgm_file db 
cmd_line db 
parm_blk db 
reg save db 


e 
e 


begin: 
set_block 
exec 


Dir (directory) command with the /W (wide) 


"command.com" ,0 
9,"/c dir /w",0DH 


14 dup (?) 
10 dup (?) 


last_inst 
pgm_file,cmd_line,parm_b1lk,0 ;THIS FUNCTION 


See Function 4AH 
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Load Overlay(Function 4BH, Code 03H) 


Call 
AH = 4BH 
AL = 03H 
DS :DX 
Pointer to pathname 
ES :BX 
Pointer to parameter block 


AX: 
BX: 
Cx: 


DX: 


Return 
Carry set: 


AX 
ro 
1. 
2 


Invalid function 
File not found 
8 Insufficient memory 
10 Bad environment 
Carry not set: 
No error 


Function 4BH, Code 03H loads a program segment (overlay). 
DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the drive and pathname of 
the program file. BX must contain the offset (from the 
segment address in ES) of a parameter. block. AL must 
contain 3. 


MS-DOS assumes that the invoking program is loading into its 
own address space, so no free memory iS required. A Program 
Segment Prefix is not created. 


The parameter block is four bytes long: 


Offset Length 


(Hex) (Bytes) Description 

00 2 (word) Segment address where program is to 
be loaded. 

02 2 (word) Relocation factor. This is usually 


the same as first word of the 
parameter block; for a description 
of an .EXE file and relocation, see 
Chapter 5). 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX. 
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Code Meaning 
1 AL is not OOH or O3H. 
2 Program file not found or path is invalid. 
8 Not enough memory to load the program. 
Macro Definition: exec _ovl macro path,parms,seg addr 
mov dx,offset path 
MOv bx,offset parms 
mov parms,seg addr 
mov parms[02H],seg addr 
mov al,3 
mov ah, 4BH 
int 21H 
endm 
Example 
The following program opens a file named TEXTFILE.ASC, 


redirects standard input to that file, loads MORE.COM as an 
overlay, and calls MORE.COM. MORE.COM reads TEXTFILE.ASC as 
Standard input. 


stdin equ 0 


file db 
cmd file db 


"TEXTFILE.ASC",0 
"\more.com",0 


parm blk dw 4 dup (?) 

handle dw ? 

new mem dw i 

U 

begin: set_block last_inst 7see Function 4AH 
jc setblock error ;routine not shown 
allocate memory 2000 ;see Function 48H 
jc _ allocate error sroutine not shown 
mOv new mem,ax ;Save seg of memory 


open_handle file,0O ssee Function 3DH 


jc open error sroutine not shown 
mov handle,ax save handle 

xdup2 handle,stdin see Function 45H 
jc dup2_ error ;routine not shown 
close handle handle ssee Function 3EH 
je close error ;routine not shown 
Mov ax ,new_mem saddr of new memory 


SYSTEM CALLS 


=e 


exec ovl cmd file,parm blk,ax 


1c 

mov 

sub 

mov 

call 

push 

pop 

free memory 
jc 


exec error 
ax,new_mem 
ax, 10h 
ds,ax 
cs:overlay 
cs 

ds 

new_mem 
free error 
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;THIS FUNCTION 
sroutine not shown 
;point to overlay 
sno PSP for overlay 
7;DS for overlay 
:;call the overlay 
srestore DS to 
;Original segment 
ssee Function 49H 
sroutine not shown 
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End Process (Function 4CH) 


gh Call 
a AH = 4CH 
CX: AL 
_ Return code 
seas Return 
ae None 
a ae 
Sl 
[races | RAGS: | 
ak: 
i 
pS 


Function 4CH terminates a process and returns to MS-DOS. AL 
contains a return code that can be retrieved by the parent 
process with Function 4DH (Get Return Code of Child Process) 
or the If command using ERRORLEVEL. 


MS-DOS closes all open handles, ends the current process, 
and returns control to the invoking process. 


This function request doesn't require that CS contain’ the 
segment address of the Program Segment Prefix. You should 
use it to end a program (rather than Interrupt 20H or a jump 
to location 0) unless it is absolutely imperative that your 
program be compatible with pre-2.0 versions of MS-DOS. 


Macro Definition: end process macro return_code 


mov al,return code 
mov ah , 4CH 
int 21H 


endm 
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Example 


The following program displayS a message and returns’ to 
MS-DOS with a return code of 8. It uses only the opening 
portion of the sample program skeleton shown at the 
beginning of this chapter. 


message db "Displayed by FUNC_4CH example" ,0DH,0AH,"$" 
begin: display message ;See Function 09H 

end process 8 ;THIS FUNCTION 
code ends 


end code 
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Get Return Code of Child Process (Function 4DH) 


AX: Call 
BX: AH = 4DH 
Cx: 
Bi Return 
AX 
a ae Return code 
ye = Re 
fee ed 
oo 
| cs 
a ee 
pS 
| es 


Function 4DH retrieves the return code specified when a 
child process terminated with either Function 31H (Keep 
Process) or Function 4CH (End Process). The code is 
returned in AL. AH returns a code that specifies the reason 
the program ended: 


Code Meaning 


0 Normal termination. 

1 Terminated by Control-C. 

2 Critical device error. 

3 Function 31H (Keep Process). 


The exit code can be retrieved only once. 


Macro Definition: ret code macro 


mov ah, 4DH 
int 21H 
endm 


Example 


Because the meaning of a return code varies, no example is 
included for this function request. 
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Find First File (Function 4EBH) 


a Call 

oe AH = 4EH 

x [om {| a DS:DX_ 

ox | om | om | 4 Pointer to pathname 


Attributes to match 


Return 
Carry set: 


ou 


18 No more files 
Carry not set: 
No error 


no OP a! 
a ae 
aa eas 
an ae 
AX 
2 File not found 
| lcs 
| os 
| ss 
| ces 


Function 4EH searches the specified or current directory for 
the first entry that matches the specified pathname. DX 
must contain the offset (from the Segment address in DS) of 
an ASCIZ string that specifies the pathname that can include 
wildcard characters. CX must contain the attribute to be 
used in searching for the file, as described in Section 
1.5.6, "File Attributes," earlier in this chapter. 


If the attribute field is hidden file, system file, or 
directory entry (02H, 04H, or 10H), or any combination of 
those values, all normal file entries are also searched. To 
search all directory entries except the volume label, set 
the attribute byte to 16H (hidden file and system file and 
directory entry). | 


If a directory entry is found that matches the name_ and 
attribute, the current DTA is filled as follows: 


Offset Length Description 

00H 21 Reserved for subsequent Find Next 
File (Function Request 4FH). 

15H 1 Attribute found. 

16H 2 Time file was last written. 


18H 2 Date file was last written. 


SYSTEM CALLS 


1AH 2 
1CH 2 
LEH 13 


Tf there is an err 
error code is retu 
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Low word of file size. 
High word of file size. 


Name and extension of the file, 
followed by OOH. All blanks are 
removed; if there is an extension, it 
is preceded by a period (it appears 
just as you would enter it ina 
command) . 


or, the carry flag (CF) is set and _ the 
rned in AX: 


Code Meaning 
2 The specified path is invalid or doesn't exist. 
18 No matching directory entry was found. 


Macro Definition: 


Example 


The following prog 
whether a file 
directory on the d 


yes db 

no db 

path db 

buffer db 

v 

begin: set_dta 
find fi 
jc 
cmp 
je 
display 
jmp 


not there: display 


find first file macro path,attrib 


MOv dx,offset path 
mov cx,attrib 

mov ah , 4EH 

int 21H 

endm 


ram displays a message that specifies 
named REPORT.ASM exists in the current 
isk in drive B. 


"FILE EXISTS.",0DH,OAH,"S$" 
"FILE DOES NOT EXIST.",0DH,OAH,"S$" 
"b:report.asm",0 


43 dup (?) 

buffer :See Function 1AH 
rst file path,0 ;THIS FUNCTION 

error findfirst ;Routine not shown 

al,12H *File found? 

not there >No 

yes | ;See Function 09H 

return sAll done 

no :See Function 09H 


“oN 
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Find Next File (Function 4FH) 


Call 
AH = 4FH 


Return 
Carry set: 
AX 
18 = No more files 
Carry not set: 
No error 


Function 4FH searches for the next directory entry that 
matches the name and attributes specified in a previous 
Function 4EH (Find First File). The current DTA must 
contain the information filled in by Function 4EH (Find 
First File). 


If a matching entry is found, the current DTA is filled just 
as it was for Find First File (see the previous function 
request description). 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


NO 


The specified path is invalid or doesn't exist. 
18 No matching directory entry was found. 


Macro Definition: find next file macro 
mov ah, 4FH 
int 21H 
endm 


SYSTEM CALLS 


Example 
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The following program displays the number of files in the 
current directory on the disk in drive B. 


message 
files 
path 
buffer 


begin: 


search dir: 


cone: 
all_ done: 


set _dta 


find first file 


jc 
cmp 
je 
inc 


"No files",0DH,0AH,"S" 


? 
"be*, *" 70 
43 dup (?) 


buffer 
al,12H 


all_done 
Files 


find next file 


jc 

cmp 

je 

inc 

jmp 
convert 
display 


error findnext 
al,12H 

done 

files 

search dir 


path,0 
error findfirst 


See Function l1AH 

;See Function 4EH 
sROoutine not shown 
;Directory empty? 
7;Yes, go home 

;No, bump file counter 
;THIS FUNCTION 
;Routine not shown 
;Any more entries? 
;No, go home 

;Yes, bump file counter 
sAnd check again 


files,10,message ;See end of chapter 


message 


>See Function 09H 


SYSTEM CALLS Function 4FH Page 1-203 


Get Verify State (Function 548) 


BX: AH = 54H 
Cx: 
au Return 
AL 
[| SP 0 = No verify after write 
| BP 1 = Verify after write 
a ee 
ie See 
aa eee 
[race | races | 
a sae 
a aie 
a as 
a ae 


Function 54H checks whether MS-DOS verifies write operations 
to disk files. The status is returned in AL: 0 if verify 
is off, 1 if verify is on. 


You can set the verify status with Function 2EH (Set/Reset 
Verify Flag). 


Macro Definition: get verify macro 


mov ah,54H 
int 21H 
endm 


Example 


The following program displays the verify status: 


message db "Verify ","$" 

on db "on.",0DH,0AH,"S" 

of f db "off.",O0DH,0OAH,"S$" 

begin: display message -See Function 09H 
get verify THIS FUNCTION 
cmp al,0 sIs flag off? 
ig ver on *No, it's on 
display off See Function 09H 
jmp return :Go home 


ver on: display on >See Function 09H 
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Change Directory Entry (Function 56H) 


Call 
AH = 56H 
DS :DX 
Pointer to pathname 
-ES:DI 
Pointer to second pathname 


AX: 
Bx: 
Cx: 
Dx: 


Return 
Carry set: 


= File not found 
5 = Access denied 
17 = Not same device 
Carry not set: 
No error 


Function 56H renames a file by changing its directory entry. 
DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that contains the pathname of the entry 
to be changed. DI must contain the offset (from the segment 
address in ES) of an ASCIZ string that contains a_ second 
pathname to which the first is to be changed. 


If a directory entry for the first pathname exists, it is 
changed to the second pathname. 


The directory paths need not be the same; in effect, you 
can move the file to another directory by renaming it. You 
cannot use this function request to copy a file to another 
drive, however: if the second pathname specifies a drive, 
the first pathname must specify or default to the same 
drive. 


This function request cannot be used to rename aé_e hidden 
file, system file, or subdirectory. If there is an error, 


the carry flag (CF) is set and the error code is returned in 
AX. 
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Code Meaning 
2 One of the paths is invalid or not open. 
5 The first pathname specifies a directory, the 
second pathname specifies an existing file, or 
the second directory entry could not be opened. 


17 Both files are not on the same drive. 


Macro Definition: rename file macro old path,new_path 


mov dx,offset old _pat 
push ds 

pop es 

MOV di,offset new_path 
mov ah,56H 

int 21H 

endm 


Example 


The following program prompts for the name of a file and a 
new name, then renames the file. 


promptl db "Filename: $" 

prompt2 db "New name: $" 

old path db 15,?,15 dup (?) 

new path db 15,?,15 dup (?) 

crlf db ODH,OAH,"S$" 

begin: display promptl ;See Function 09H 
get string 15,old path ;See Function OAH 
xOr bx ,bx 7TO use BL as index 
mov bl1,old path[1] *Get string length 
mov old path[bx+2],0 ;Make an ASCIZ string 
display crlf 7See Function 09H 
display prompt2 ;See Function 09H 
get string 15,new path :See Function OAH 
xOr bx , bx :TO use BL as index 
mov bl,new path[1] *Get string length 
mMOv new path[bx+2],0 ;Make an ASCIZ string 
display crlf 7;See Function 09H 


rename file old path[2],new_path[2];THIS FUNCTION 
je error rename ;Routine not shown 
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Get/Set Date/Time of File(Function 57H) 


AX: fos 
BX: 57H 

Function code 

Get date and time 


- Set date and time 


CX: Dy 
Ox: fo 


Handle 
CX (if AL=1) 

Time to be set 
DX (if AL=1) 

Date to be set 


Return 
Carry set: 
AX 
1 Invalid function 


6 = Invalid handle 
Carry not set: 
CX (if AL=0) 
Time file last written 
DX (if AL=0) 
Date file last written 
Function 57H gets or sets the time and date a file was’ last 
written. To get the time and date, AL must contain 0; _ the 
time and date are returned in CX and DX. To set the time 
and date, AL must contain 1; CX and DX must contain the 
time and date. BX must contain the file handle. The time 


and date are in the form described in "Fields of the FCB" in 
Section 1.8.1. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX: 


Code Meaning 
L AL is not 0 or l. 
6 The handle in BX is invalid or not open. 


Macro Definition: 


get_set date time macro handle,action,time,date 


Mov bx,handle 

mov al,action 

mMOv cx,word ptr time 
mov dx,word ptr date 
Mov ah,57H 

int 21H 


endm 


SYSTEM CALLS 


Example 


Function 57H 


The following program gets’7 the 
REPORT.ASM in the current directory on the disk in drive B, 


increments’ the 


day, increments 
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of the file named 


month or year if 


necessary, and sets the new date of the file. 


month ab 
path db 
handle dw 
time db 
date db 
begin: 

mov 


31,28,31,30,31,30,31,31,30,31,30,31 


"b:report.asm",0 


? 
2 dup (?) 
2 dup (?) 


open_handle path,0 


handle,ax 


See Function 3DH 
Save handle 


get_set_ date time handle,0,time,date;THISFUNCTION 


jc 
mMOv 
mov 


error time 
word ptr time,cx 
word ptr date,dx 


convert date date[-24] 


inc 
xOr 
Mov 
cmp 
jle 
mov 
inc 
cmp 
jle 
mov 
inc 


dh 

bx, bx 

bl,dl 

dh,month [bx-1] 


d1,12 
month ok 
di,1 

cx 


month ok: pack date date 
get set date time handle,1,time,date;THISFUNCTION 


jc 


error time 


close handle handle 


jc 


error close 


sRoutine not shown 
;Save time 

;Save date 

7;See end of chapter 
s;Increment day 

*To use BL as index 
;Get month 

;Past last day? 

sNo, go home 

;Yes, set day to l 
;Increment month 

7Is it past December? 
:No, go home 

;Yes, set month to 1 
Increment year 

See end of chapter 


:Routine not shown 
See Function 3EH 
Routine not shown 
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Get/Set Allocation Strategy (Function 58H) 


exe Call 
ze, WE AH = 58H 
Cx: AL 
Be 0 = Get strategy 
1 = Set strategy 
BX (AL=1) 
0 = First fit 
1 = Best fit 
2 = Last fit 
Return 
Carry set: 
AX 


1 = Invalid function code 
Carry not set: 


AX (AL=0) 
0 = First fit 
1 = Best fit 
2 = Last fit 


Function 58H gets or sets the strategy used by MS-DOS to 
allocate memory when requested by a process. If AL contains 
0, the strategy is returned in AX. If AL contains 1, BX 
must contain the strategy. The three possible strategies 
are: 


Value Name Description 


0 First fit MS-DOS starts searching at the lowest 
available block and allocates the first 
block it finds (the allocated memory is 
the lowest available block). This is the 
default strategy. 


1 Best fit MS-DOS searches each available block and 
allocates the smallest available block 
that satisfies the request. 


2 Last fit MS-DOS starts .searching at the highest 
available block and allocates the first 
block it finds (the allocated memory is 
the highest available block). 


You can use this function request to control how MS-DOS uses 
its memory resources. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX. 
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Code Meaning 
1 AL doesn't contain 0 or 1, or BX doesn't contain 
0, l, or 2. 
Macro Definition: alloc strat macro code,strategy 
MOv bx, Strategy 
mov al,code 
mov ah, 58H 
int 21H 
endm 


Example 


The following program displays’ the memory allocation 
strategy in effect, then forces Subsequent memory 
allocations to the top of memory by setting the strategy to 
last fit (code 2). 


get equ 0 

set equ ii 

stdout equ a 

last fit equ 2 

first db "Pirst fit ",0DH,OAH 

best db "Best fit ",0ODH, OAH 

last db "Last fit ",O0DH, OAH 

Ul 

begin: alloc strat get sTHIS FUNCTION 
jc alloc _error sroutine not shown 
Mov cl1,4 smultiply code by 16 
shl ax,cl sto calculate offset 
Mov dx,offset first spoint to first msg 
add adx,ax sadd to base address 
MOv bx,stdout shandle for write 
mov cs,16 swrite 16 bytes 
mov ah,40h swrite handle 
int 21H -system call 

: jc write error sroutine not shown 
alloc strat set,last fit >THIS FUNCTION 


je alloc_error sroutine not shown 


=e 
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Get Extended Error (Function 59H) 


AX: Call 
BX: AH = 59H 
CX: BX = 0 
DX: 
Return 
| se AX 
| oP Extended error code 
penne aE BH 
ee ae Error class (see text) 
BL 
a Suggested action (see text 
Paar] gg 
a Locus (see text) 
PS 
[sss CL, DX, SI, DI, BP, DS, ES destroyed 
a ae 


Function 59H retrieves an extended error code for _ the 
immediately previous system call. Each release of MS-DOS 
extends the error codes to cover new capabilities. These 
new codes are mapped to a Simpler set of error codes based 
on Version 2.0 of DOS, so that existing programs’ can 
continue to operate correctly. Note that all registers 
except CS:IP and SS:SP are destroyed by this call. 


A user-written Interrupt 24H handler can use Function 59H 
(Get Extended Error) to get detailed information about the 
error that caused the interrupt to be issued. 


The input BX is a version indicator which says what level of 
error handling the application was written for. The current 
level is 0. 


The extended error code consists of four separate codes’ in 
AX, BH, BL, and CH that give as much detail as possible 
about the error and suggest how the issuing program’ should 
respond. 


SYSTEM CALLS 
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BH -- Error Class 


BH returns a code that describes the class of error that 


occurred: 
Class Description 

i Out of a resource, such as storage or channels. 

2 Not an error, but a temporary Situation (Such as a 
locked region in a file) that can be expected to end. 

3 Authorization problem. 

4 An internal error in System software. 

5 Hardware failure. 

6 A system software failure not the fault of the active 
process (could be caused by missing or incorrect 
configuration files, for example). 

7 Application program error. 

8 File or item not found. 

9 File or item of invalid format, type, or otherwise 
invalid or unsuitable. 

10 File or item interlocked. 

11 Wrong disk in drive, bad spot on disk, or other 
problem with storage medium, 

12 Other error. 


BL -- Suggested Action 


BL returns a code that suggests how the issuing program can 
respond to the error: 


Action Description 


1 


2 


Retry, 


then prompt user. 


Retry after a Pause. 


Tf the user entered data such as a drive letter or 
file name, prompt for it again. 


Terminate with cleanup. 


Terminate immediately. The system is so unhealthy 
that the program should exit as soon as possible 
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without taking the time to close files and update 


indexes. 
6 Error is informational. 
7 Prompt the user to perform some action, such as 


changing disks, then retry the operation. 


CH -- Locus 


CH returns a code that provides additional information to 
help locate the area involved in the failure. This code is 
particularly useful for hardware failures (BH=5). 


Locus Description 


1 Unknown. 

2 Related to random access block devices, such aS a 
disk drive. 

3 Related to Network. 

4 Related to serial access character devices, such 


aS a printer. 
5 Related to random access memory. 


Your programs should handle errors by noting the error 
return from the original system call, then issuing this 
system call to get the extended error code. If the program 
does not recognize the extended error code, it should 
respond to the original error code. 


This system call is available during Interrupt 24H and may 
be used to return network-related errors. 


Macro Definition: get_error macro 


mov ah, 59H 
int 21H 
endm 


Example 


Because so much detail is provided by this function request, 
an example is not shown. User programs can interpret the 
various codes to determine what sort of messages or prompts 
should be displayed, what action to take, and whether to 


terminate the program if recovery from the errors isn't 
possible. 
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Create Temporary File (Function 5AH) 


AX: 
BX: 
Cx: 
Attribute 
DS :DX 
Pointer to pathname followed by a 
byte of 0 and 13 bytes of memory 


Return 

Carry set: 

AX 

Path not found 
5 Access denied 

Carry not set: 

AX 
Handle 


eS) 
Hol 


Function 5AH creates a file with a unique name. DX must 
contain the offset (from the segment address in DS) of an 
ASCIZ string that specifies a pathname and 13 bytes of 
memory (to hold the filename). CX must contain the 
attribute to be assigned to the file, as described in 
Section 1.5.6, "File Attributes," earlier in this chapter. 


MS-DOS creates a unique filename and appends it to the 
pathname pointed to by DS:DX, creates the file and opens it 
in compatibility mode, then returns the file handle in Ax. 
A program that needs a temporary file should use this 
function request to avoid name conflicts. 


MS-DOS does not automatically delete a file created with 
Function 5AH when the creating process exits. When the file 
is no longer needed, it should be deleted. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX: 


Code Meaning 


3 The directory pointed to by DS:DX is invalid or 
doesn't exist. 


5 Access denied. 
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Macro Definition: create temp macro pathname,attrib 


mov cx,attrib 

mov dx,offset pathname 

mov ah, 5AH 

int 21H 

endm j 


/ 


Example ( 
The following program creates a temporary file in the 
directory named \WP\DOCS, copies a file in the current 
directory named TEXTFILE.ASC into the temporary file, then 
closes both files. 


stdout equ 1 

a 

file db "TEXTFILE.ASC",0 

path db "\ WP\DOCS" ,0 

temp db 13 dup (0) 

Open _msg db " opened." ,0ODH, OAH 

crl msg db " created.",0DH,0OAH 

rd msg db "read into buffer.",0DH,0OAH 

wr msg db "Buffer written to " 

cl msg db "Files closed.",0DH,OAH 

crlf db ODH, OAH 

handlel dw ? 

handle2 dw ? 

buffer db 512 dup (?) 

0 

begin: open handle file,0O ssee Function 3DH 
jc open_error sroutine not shown 
mov handlel,ax save handle 
write handle stdout, file,12 ;see Function 40H 
jc write error sroutine not shown 
write handle stdout ,open _msg,10 ;see Function 40H 
7c write error sroutine not shown 
create temp path,0 ;THIS FUNCTION 
je create error ;routine not shown 
mv handle2,ax save handle 
write handle stdout, path, 8 ssee Function 40H 
jc write error sroutine not shown 
display char ee ;see Function 02H 
write handle stdout,temp,12 s:see Function 40H 
je write error ;routine not shown 
write handle stdout,crl_msg,1l1 ;See Function 40H 
je write error ;routine not shown 
read_handle handlel,buffer,512 ;:see Function 3FH 
jc read error sroutine not shown 
write handle stdout,file,12 see Function 40H 
jc write error zroutine not shown 
write handle stdout,rd_msg,20 ;see Function 40H 
jc write error ;routine not shown 
write handle handle2,buffer,512 ;see Function 40H 
jc write error ;routine not shown 


write handle stdout,wr _msg,18 ;see Function 40H 
jc write error ;routine not shown 


SYSTEM CALLS 


write 


jc 


write_ 


jc 


close _ 


jc 


close _ 


je 


write 


jc 
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handle stdout,temp,12 >see Function 40H 


write error sroutine not shown 
handle stdout,crlf,2 ssee Function 40H 
write error s;routine not shown 
handle handlel :see Function 3EH 
close error ;routine not shown 
handle handle2 see Function 3EH 
close error ;routine not shown 
handle stdout,cl_msg,15 ;see Function 40H 
write error ;routine not shown 
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Create New File (Function 5BH) 


AX: 
BX: 
CX: 
Attribute 
DS :DX 
Pointer to pathname 


DX: 


Return 
Carry set: 


Path not found 

Too many open files 
Access denied 

File already exists 
Carry not sets: 


‘= 
uonou wu 


Function 5BH creates a new file. DX must contain the offset 
(from the segment address in DS) of an ASCIZ string that 
specifies a pathname. CX contains the attribute to _ be 
assigned to the file, as described in Section 1.5.6, "File 
Attributes." 


If there is no existing file with the same filename, MS-DOS 
creates the file, opens it in compatibility mode, and 
returns the file handle in AX. 


Unlike Function 3CH (Create Handle), this function request 
fails if the specified file exists, rather than truncating 
it to a length of 0. The existence of a file is used as a 
semaphore in a multitasking system; you can use this system 
call as a test-and-set semaphore. 


SYSTEM CALLS 
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If there is an error, the carry flag (CF) is set and the 
error code is returned in AX: 
Code Meaning 
3 The directory pointed to by DS:DX is invalid or 
doesn't exist. 
4 No free handles are available in the current 
process, or the internal system tables are full. 
5 Access denied. 
80 A file with the same specification pointed to by 


DS:DX already exists. 


Macro Definition: create new macro 
= mov 
mov 
mov 
int 
endm 


Example 


The following program attempts to create a new file in 
named REPORT.ASM. 


current directory 


pathname,attrib 

cx, attrib 

dx, offset pathname 
ah, 5BH 

21H 


the 
If the file already 


exists, the program displays an error message and returns to 


MS-DOS. If the 
errors, the program saves’ the 
processing. 
err msg db 
path db “REPORT .ASM" ,0 
handle dw ? 
begin: create new path,0 
jnc continue 
cmp ax , 80 
jne error 
display err msg 
jmp return 
continue: mov handle,ax 


=e m6 


(further processing here) 


file doesn't exist and there are no other 
handle 


and continues 


"PILE ALREADY EXISTS",0DH,OAH,"S" 


THIS FUNCTION 
;further processing 
;file already exist? 
sroutine not shown 
see Function 09H 
;return to MS-DOS 
s;save handle 
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Lock (Function 5CH, Code 008) 


ax: f Call 
a | AH = 5CH 
ox f AL = 00H 
B 
a Handle 
CX:DX 
Offset of region to be locked 
ST:DI 
Length of region to be locked 
Return 
Carry set: 
AX 
1 = Invalid function code 
6 = Invalid handle 
22 = Lock violation 


Carry not set: 
No error 


Function 5CH, Code 00H denies all access (read or write) by 
any other process to the specified region of the file. BX 
must contain the handle of the file that contains the region 
to be locked. CX:DX (a 4-byte integer) must contain the 
offset in the file of the beginning of the region. SI:DI (a 
4-byte integer) must contain the length of the region. 


If another process attempts to use (read or write) a locked 
region, MS-DOS retries three times; if the retries fail, 
MS-DOS issues Interrupt 24H for the requesting process. You 
can change the number of retries with Function 44H, Code OBH 
(IOCTL Retry). 


The locked region can be anywhere in the file. Locking 
beyond the end of the file is not an error. A region should 
be locked for a brief period; it should be considered an 
error if a region is locked for more than 10 seconds. 


Function 45H (Duplicate File Handle) and Function 46H (Force 
Duplicate File Handle) duplicate access to any locked 
region. Passing an open file to a child process with 
Function 4BH, Code 00H (Load and Execute Program) does not 
duplicate access to locked regions. 


Tf a program closes a file that contains a locked region or 
terminates with an open file that contains a locked region, 
the result is undefined. Programs that might be terminated 
by Interrupt 23H (Control-C) or Interrupt 24H (a fatal 
error) should trap these interrupts and unlock any _ locked 
regions before exiting. 
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Programs should not rely on being denied access to a_ locked 
region; a program can determine the status of a region 
(locked or unlocked) by attempting to lock the region and 
examining the error code. 


Tf there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 
i File sharing must be loaded to use this function 
request. 
6 The handle in BX is not a valid, open handle. 
33 All or part of the specified region is already 
locked. 
Macro Definition: lock macro  handle,start,bytes 
mov bx, handle 
MOV cx, word ptr start 
MOV dx, word ptr start+2 
Mov Si, word ptr bytes 
mov di, word ptr bytes+2 
mov al, 0 
mov ah, 5CH 
int 21H 
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Example 


The following program opens a file named FINALRPT in Deny 
None mode and locks two portions of it: the first 128 bytes 
and bytes 1024 through 5119. After some (unspecified) 


processing, it unlocks the same portions and closes the / 


file. 

stdout equ 1 

startl dd 0 

lgthl dd 128 

start2 dd 1023 

Igth2 dd 4096 

file db "FINALRPT",0 

op msg db " opened.",0ODH, OAH 

ll msg dab "Pirst 128 bytes locked.",0ODH, OAH 

12 msg db "Bytes 1024-5119 locked.",ODH, OAH 

ul msg db "First 128 bytes unlocked.",0DH, OAH 

u2 msg db "Bytes 1024-5119 unlocked.",0DH, OAH 

cl msg db " closed.:,0DH,0AH 

handle dw ? 

begin: open_handle £File,01000010b ;see Function 3DH 
jc open error sroutine not shown 
write handle stdout,file,8 ;see Function 40H 
jc write error sroutine not shown 
write handle stdout,op msg,10 ;see Function 40H 
jc write error sroutine not shown 
mov handle,ax :save handle 
lock handle,startl,lgthl ;THIS FUNCTION 
jc lock error sroutine not shown 
write handle stdout,11 msg,25 ;see Function 40H 
je write error ;routine not shown 
lock handle,start2,lgth2 ;THIS FUNCTION 
jc lock error sroutine not shown 
write handle stdout ,12 _msg,25 ;see Function 40H 
jc write error sroutine not shown 


( Further processing here ) 


=e “6 ~O 


unlock handle,startl,lgthl ;See Function 5C01H 
je unlock error ;routine not shown 
write handle stdout,ul_msg,27 ;see Function 40H 
jc write error sroutine not shown 
unlock handle,start2,lgth2 ;See Function 5C01H 
je unlock error ;routine not shown 
write handle stdout ,u2 _msg,27 ;See Function 40H 
jc write error sroutine not shown 
close_handle handle See Function 3EH 
jc close error sroutine not shown 
write handle stdout,file,8 ;see Function 40H 
jc write error sroutine not shown 


write handle stdout,cl _msg,10 ;see Function 40H 
je write error zroutine not shown 


\ 
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Unlock (Function 5CH, Code 01H) 


AX Call 
BX AH = 5CH 
cx AL = O1H 
DX: BX 
Handle 
CX:DX 
Offset of area to be unlocked 
SI:DI 
Length of area to be unlocked 
Return 
Carry set: 
AX 
1 = Invalid function code 
6 = Invalid handle 
22 = Lock violation 


Carry not set: 
No error 


Function 5CH, Code 01H unlocks a region previously locked by 
the same process, BX must contain the handle of the file 
that contains the region to be unlocked. CX:DX (a 4-byte 
integer) must contain the offset in the file of the 
beginning of the region. SI:DI (a 4-byte integer) must 
contain the length of the region. The offset and length 
must be exactly the same as the offset and length specified 
in the previous Function 5CH, Code OOH (Lock). 


The description of Function 5CH, Code 00H (Lock) describes 
how to use locked regions. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 
1 File sharing must be loaded to use this function 
request. 
6 The handle in BX is not a valid, open handle. 
33 The region specified is not identical to one 


that was previously locked by the same process. 


SYSTEM CALLS 


Macro Definition: 


Example 


The following program opens a file named FINALRPT in 
None mode and locks two portions of it: 
and bytes 


1024 


processing, it 


fille. 
stdout 


startl 
Igthl 

start2 
Igth2 

file 

op_msg 
1ll_msg 
12 msg 
ul_msg 
u2_msg 
cl msg 
handle 


begin: 


~e 8 ne 


open_ handle file,01000010b 

jc open _error 

write handle stdout,file,8 
write error 

write handle stdout,op msg,10 
write error 


jc 
jc 
mov 
lock 
jc 
jc 
lock 


jc 


unlock 
je 
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unlock macro handle,start,bytes 
mov bx, handle 
mov cx, word ptr start 
Mov dx, word ptr start+2 
mov Si, word ptr bytes 
MOV di, word ptr bytes+2 
Mov al, l 
mov ah, 5CH 
int 21H 
endm 


Deny 
the first 128 bytes 
through 5119. After some (unspecified) 
unlocks the same portions and closes the 
1 
0 
128 
1023 
4096 
"FINALRPT" ,0 


" opened.",0ODH, OAH 

"First 128 bytes locked.",0DH,0AH 
"Bytes 1024-5119 locked.",0DH,0OAH 
"First 128 bytes unlocked.",0ODH, OAH 
"Bytes 1024-5119 unlocked." ,0DH,0AH 
" closed." 


2 


handle,ax 


handle,startl,lgthl 
lock error 

write handle stdout,11l _msg,25 
write error 
handle,start2,lgth2 
jc lock error 

write handle stdout,12 _msg,25 
write error 


handle,startl,lgthl 
unlock error 
write handle stdout,ul_ msg, 27 


( Further processing here ) 


,ODH , OAH 


ssee Function 3DH 
sroutine not shown 
see Function 40H 
routine not shown 
ssee Function 40H 
sroutine not shown 
:;save handle 

See Function 5C00H 
sroutine not shown 
see Function 40H 
sroutine not shown 
*See Function 5C00H 
sroutine not shown 
ssee Function 40H 
sroutine not shown 


sTHIS FUNCTION 
sroutine not shown 
:see Function 40H 
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je write error ;routine not shown 
unlock handle,start2,lgth2 ;THIS FUNCTION 

jc unlock error sroutine not shown 
write handle stdout,u2_msg,27 ;see Function 40H 
je write error sroutine not shown 
close handle handle ;See Function 3EH 
jc close error sroutine not shown 
write handle stdout,file,8 ssee Function 40H 
jc” write error sroutine not shown 


write handle stdout,cl_msg,10 ;see Function 40H 
je write error ;routine not shown 
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Get Machine Name (Function 5EH, Code 008) 


Call 
AH = 5EH 
AL = 0 
DS :DX 
Pointer to 16-byte buffer 


Return 
Carry set: 
AX 
1 = Invalid function code 
Carry not set: 
CX 
Identification number of local 
computer 


Function 5EH, Code 0 retrieves the net name of the _ local 
computer. DX must contain the offset (to the segment 
address in DS) of a 16-byte buffer. Microsoft Networks must 
be running. 


MS-DOS returns the local computer name (a 16-byte ASCIZ 
string, padded with blanks) in the buffer pointed to by 
DS:DX. CX returns the identification number of the local 
computer. 

Code Meaning 


1 Microsoft Networks must be running to use this 
function request. 


Macro Definition: get_machine name macro buffer 


mov dx,offset buffer 
mov al,0 

mov ah,5EH 

int 21H 


endm 


ao 
\ 
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Example 


The following program displays the name 
Networks workstation. 


stdout equ l 


c 


msg db "Netname: " 

mac_ name db 16 dup (?),0DH,0OAH 

begin: get_machine name mac_name 
je name_error 
write handle stdout,msg,27 
jc write error 
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of a Microsoft 


>THIS FUNCTION 

sroutine not shown 
see Function 40H 
sroutine not shown 
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Printer Setup (Function 5EH, Code 02H) 


= 5EH 
AL = 02H 


Assign list index 
Length of setup string 
Pointer to setup string 


DS:SI 
Pointer to string 


Return 
Carry set: 
AX 
1 = Invalid function code 
Carry not set: 
No error 


Function 5EH, Code 02H defines aie string of control 
characters that MS-DOS adds to the beginning of each file 
sent to the network printer. BX must contain the index into 
the assign list that identifies the printer (entry 0 is the 
first entry). CX must contain the length of the string. SI 
must contain the offset (to the segment address in DS) of 
the string itself. Microsoft Networks must be running. 


The setup string is added to the beginning each file sent to 
the printer specified by the assign list index in BX. This 
function request lets each program that shares a printer 
have its own printer configuration. You can determine which 
entry in the assign list refers to the printer with Function 
5FO2H (Get Assign List Entry). 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


1 Microsoft Networks must be running to use this 
function request. 
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Macro Definition: printer setup macro index,lgth,string 


mov bx, index 

mov cx, lgth 

MOV dx, offset string 
mov al, 2 

mov ah, 5EH 

int 21H 

endm 


Example 


The following program defines a printer setup string that 
consists of the control character to print expanded type on 
Epson (R)-compatible printers. The printer cancels this mode 
at the first Carriage Return, so the effect is to print the 
first line of each file sent to the network printer as a 
title in expanded characters. The setup string is one 
character. This example assumes that the printer is’ the 
entry number 3 (the fourth entry) in the assign list. Use 
Function 5F02H (Get Assign List Entry) to determine this 
value. 


setup db OEH 


begin: printer setup 3,1,setup >sTHIS FUNCTION 
jc error sroutine not shown 
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Get Assign List Entry (Function 5FH, Code 02H) 


= 5FH 
AL = 02H 


Assign list index 
DS:SI . 

Pointer to buffer for local name 
ES :DI 

Pointer to buffer for remote name 


Return 

Carry set: 

AX 
1 Invalid function code 
18 No more files 

Carry not set: 

BL 


Printer 
Drive 


3 
4 


CX 
Stored user value 


Function 5FH, Code 02H retrieves the specified entry from 
the network list of assignments. BX must contain the assign 
list index (entry 0 is the first entry). SI must contain 
the offset (to the segment address in DS) of a 16-byte 
buffer for the local name. DI must contain the offset (to 
the segment address in ES) of a 128-byte buffer for the 
remote name. Microsoft Networks must be running. 


MS-DOS puts the local name in the buffer pointed to by DS:SI 
and the remote name in the buffer pointed to by ES:DI. The 
local name can be a null ASCIZ string. BL returns 3 if the 
local device is a printer or 4 if the local device is a 
drive. CX returns the stored user value set with Function 
5FH, Code 03H (Make Assign List Entry). The contents of the 
assign list can change between calls. 


You can use this function request to retrieve any entry, or 
make a copy of the complete list by stepping through the 
table. To detect the end of the assign list, check for 
error code 18 (no more files), just as when you step through 
a directory with Functions 4EH and 4FH (Find First File and 
Find Next File). 
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If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 

Code Meaning 


us Microsoft Networks must be running to use this 
function request. 


18 The index passed in BX is greater than the 
number of entries in the assign list. 


Macro Definition: get list macro index,local,remote 


mov bx, index 

mov si, offset local 
mov di, offset remote 
mov al,2 

Mov ah, 5FH 

int 21H 

endm 


Example 


The following program displays the assign list on a 
Microsoft Networks workstation, showing the local name, 
remote name, and device type (drive or printer) for each 
entry. 


stdout equ 1 ;Code returned from 
printer equ 3 ;GetAssignListEntry for 
sa printer 
header db °13,10,13,10,"Device Type " 
db "Local name",9 dup (20h) 
db "Remote name" 

crlf db 13710-13410 
header len equ S - header 
local _ nm db 19 dup (?) 
remote nm len equ $ - local _nm 
remote nm db 128 dup (?) 
remote nm len equ $ - remote nm 
drive msg db "Drive",8 dup (20h) 
print msg db "Printer", 6 dup (20h) 
device msg len equ $ - print msg 
str_ len dw ? 
index dw ? 
begin: 

write handle stdout,header,header len :see Function 40H 

jnc set_index 

jmp write error 


set_index: 
mov index,0 sassign list index 
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ck list: get list index,local_nm,remote nm ;THIS FUNCTION 


jne got _one ;got an entry 

cmp ax,18 s;last entry? 

je last one ;yes 

jmp return ;some other error 
got_one: / 

cmp bl,printer sis it a printer? \ 

jc prntr ;yes 

write handle stdout,drive msg,device msg len 

je write error sroutine not shown 

jmp short display nms 
prntr: write handle stdout,print _msg,device msg len 

je write error ;routine not shown 
display nms: 

mov di, offset local nm 

mov cx,local_nm_len 

XOX ax,ax 

repne scasb 

dec di 

inc cx 

mov al,20h 

rep stosb 

Mov di,offset remote nm 

MOV cx,remote nm len 

xOr ax,ax - 

repne scasb 

dec di 

MOv al,13 

stosb 

mov al,10 

stosb 

mov si,offset local_nm 

sub di,si 

mMOv str len,di 

write handle stdout,local nm,str_len 

jc write error 

inc index — sbump index 

jmp ck list sget next entry 
last_one: write handle stdout,crlf,4 >see Function 40H 

jc write error 

jmp return 


write error: 


INCLUDE suffix.asm 
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Make Assign List Entry (Function 5FH, Code 03H) 


Call 

AH = 5FH 
AL = 03H 
BL 


AX: 
BX: 
CX: 


DX: 7 
Printer 


= Drive 


Pm W 


CX 
User value 
DS:SI 
Pointer to name of source device 
ES :DI 
Pointer to name of destination 
device 


Return 
Carry set: 
AX 
1 
5 


Invalid function code 
Access denied 
3 Path not found 
8 Insufficient memory 
(Other errors particular to the 
network may occur.) 
Carry not set: 
No error 


Function 5FH, Code 03H redirects a printer or disk drive 
(source device) to a network directory (destination device). 
BL must contain 3 if the source device is a printer or 4 if 
the source device is a disk drive. SI must contain the 
offset (to the segment address in DS) of an ASCIZ _ string 
that specifies either the name of the printer, a drive 
letter followed by a colon, or a null string (one byte of 
OOH). DI must contain the offset (to the segment address in 
ES) of an ASCIZ string that specifies the name of a network 
directory. CX contains a user-specified 16-bit value that 
MS-DOS maintains. Microsoft Networks must be running. 


The destination string must be an ASCIZ string of the 
following form: 


<machine-name><pathname><00H><password><0O0H> 


<machine-name> is the net name of the Server that contains 
the network directory. 


<pathname> is the alias of the network directory (not the 
directory path) to which the source device is to _ be 
redirected. 


<OOH> is a null byte. 
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<password> is the password for access to the network 
directory. If no password is specified, both null bytes 
must immediately follow the pathname. 


If BL=3, the source string must be PRN, LPT1, LPT2, or LPT3. 
All output for the named printer is buffered and sent to the 
remote printer spooler named in the destination string. 


If BL=4, the source string can be either a drive letter 
followed by a colon or a null string. If the source string 
contains a valid drive letter and colon, all subsequent 
references to the drive letter are redirected to the network 
directory named in the destination string. If the source 
string is a null string, MS-DOS attempts to grant access to 
the network directory with the specified password. 


The maximum length of the destination string is 128 bytes. 
The value in CX can be retrieved with Function 5FH, Code 02H 
Get Assign List Entry). 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX: 


Code Meaning 


1 Microsoft Networks must be running to uSe this 
function request, the value in BX is not 1 to 4, 
the source String is in the wrong format, the 
destination string is in the wrong format, or 
the source device is already redirected. 


3 The network directory path is invalid or doesn't 
exist. 
5 The network directory/password combination is 


not valid. This does not mean that the password 
itself was invalid; the directory might not 
exist on the Server. 


8 There is not enough memory for string 
substitutions. 


Macro Definition: 
redir macro device,value,source,destination 


mov bl, device 

mov cx, value 

mov si, offset source 

mov es, seg destination 
mov di, offset destination 
mov al, 03H 

mov ah, 5FH 

int 21H 
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Example 


The following program redirects two drives and a printer 
from a workstation to a Server named HAROLD. It assumes the 
machine name, directory names, and driver letters shown: 


Local drive Netname 

or printer on server Password 
Es WORD none 

F: COMM fred 
PRN: PRINTER quick 


printer equ 3 
drive equ 4 


local _1 db "e:",0 

local 2 db "“f:",0 

local_ 3 db "“prn",0 

remote 1 db "\harold\word",0,0 

remote 2 db "\harold\comm",0,"fred",0 
remote 3 db "“\harold\printer",0,"quick",0 


begin: redir local_1,remote 1,drive,0 sTHIS FUNCTION 
je error ;routine not shown 
redir local 2,remote 2,drive,0 THIS FUNCTION 
je error 7 sroutine not shown 


redir local _ 3,remote 3,printer,0 ;THIS FUNCTION 
jc error ;routine not shown 
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Cancel Assign List Entry (Function 5FH, Code 04H) 


Call 

AH = 5FH 

AL = 04H 

DS:SI / 
Pointer to name of source device \ 


Return 

Carry set: 

AX 
1 Invalid function code 
15 Redirection paused on server 
(Other errors particular to the netwo 
may occur.) 

Carry not set: 
No error 


Function 5FH, Code 04H cancels the redirection of a printer 
or disk drive (source device) to a network directory 
(destination device) made with Function 5FH, Code 03H (Make 
Assign List Entry). SI must contain the offset (to the 
segment address in DS) of an ASCIZ string that specifies the 
name of the printer or drive whose redirection is to be 
canceled. Microsoft Networks must be running. 


The ASCIZ string pointed to by DS:SI can contain one of 
three values: | 


1. The letter of a redirected drive, followed by a 
colon. The redirection is canceled and the drive 
is restored to its physical meaning. 


2. The name of a redirected printer (PRN, LPT1, LPT2, 
or LPT3). The redirection is canceled and the 
printer name is restored to its physical meaning. 


3. A string starting with \\ (2 backslashes). The 
connection between the local machine and_ the 
network directory is terminated. 
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If there is an error, the carry flag (CF) is set and_ the 
error code is returned in Ax: 


Code Meaning 


1 Microsoft Networks must be running to use this 
function request, or the ASCIZ string doesn't 
name an existing source device. 

15 Disk or printer redirection on the network 
server is paused. 


Macro Definition: cancel _redir macro local 


Mov si, offset local 
mov al, 4 

MOV ah, 5FH 

int 21H 

endm 


Example 


The following program cancels the redirection of drives E 
and F and the printer (PRN) of a Microsoft Networks 
workstation. It assumes that these local devices were 
previously redirected. 


local 1 db "e:",0 

local _2 db "f£:",0 

local _ 3 db "porn ;0 

begin: cancel redir local _l sTHIS FUNCTION 
jc error sroutine not shown 
cancel redir local 2 sTHIS FUNCTION 
je = error sroutine not shown 
cancel redir local 3 ;THIS FUNCTION 


jc error sroutine not shown 
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Get PSP (Function 62H) 


AX: Call 
BX: AH = 62H 
Cx: 
Dx: Return 
BX 
ee eee Segment address of the Program 
| Segment 
eee 26h Prefix of the current process 
pF 
a ae 
[acs | Fins | 
| cs 
ps 
esas eee 
ae en 


Function 62H retrieves the segment address of the currently 


active process (the start of the Program Segment Prefix). 
The address is returned in BX. 


Macro Definition: get psp macro 


mov ah, 62H 
int 21H 
endm 


Example 


The following program displays the segment address of its 
Program Segment Prefix (PSP) in hexadecimal. 


msg db "PSP segment address: H",0DH,0AH,"S" 
begin: get psp ;THIS FUNCTION 
convert bx, 16,msg[21] ;see end of chapter 


display msg ;see Function 09H 


REKKKKKRKKRKRKKKRKKRKRKRKEK 


Interrupts 
eKKKKKKEKKEEKEEKREKEKKK 


me @“O@ ue VEO 


INTERRUPT 25H 
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MACRO DEFINITIONS FOR MS-DOS SYSTEM CALL EXAMPLES 


ABS DISK READ macro disk,buffer,num_sectors,first sector 


MOV al,disk 

MOV bx ,offset buffer 
MOv cx,num_ sectors 
MOV dx,first sector 
int 25H 

popf 

endm 


INTERRUPT 26H 


ABS DISK WRITE macro disk,buffer,num_sectors,first sector 


mov al,disk 

mov bx,offset buffer 
mov cx,num_ sectors 
MOv dx,first sector 
int 26H = 

popf 

endm 


mov dx,offset last instruc 
inc dx 

int 27H 

endm 


REKRKEKKKKKKRKKRKRKKKRKRKK 


Function Requests 
eRKEKEKEKEKKEKKKKRKKRKKRKRKKK 


=e "6 26 WO 


~ 


a 
TERMINATE PROGRAM macro 


xOLr ah,ah 
int 21H 
endm 


e 
e 


READ KBD AND ECHO macro 


mov ah,01H 
int 21H 
endm 


DISPLAY CHAR macro character 


Mov dl,character 
mov ah,02H 

int 21H 

endm 


ti 

AUX_ INPUT macro 
mov ah,03H 
int 21H 
endm 


; INTERRUPT 27H 
STAY RESIDENT macro last instruc 


FUNCTION REQUEST 00H 


FUNCTION REQUEST 01H 


FUNCTION REQUEST 02H 


FUNCTION REQUEST 03H 


AUX OUTPUT macro 
mov ah,04H 


int 21H 
endm 
PRINT CHAR macro character 
mMOv dl,character 
mov ah,05H 
int 21H 
endm 
a 
DIR CONSOLE IO macro’ switch 
~ mov  dl,switch 
mov ah,06H 
int 21H 
endm 


DIR_CONSOLE INPUT macro 
MOV ah,07H 
int 21H 
endm 


; 
READ KBD macro 
mov ah,08H 


int 21H 
endm 
’ 
DISPLAY macro’. string 
mov dx,offset string 
MOV ah,09H 
int 21H 
endm 
GET STRING macro limit,string 
MOV dx,offset string 
mov String,limit 
MOV ah, 0AH 
int 21H 
endm 
a 
CHECK KBD STATUS macro 
MOV ah, OBH 
int 21H 
endm 
a 
FLUSH_AND READ KBD macro switch 
MOV al,switch 
mov ah, OCH 
int 21H 


endm 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 
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04H 


05H 


06H 


07H 


08H 


09H 


OAH 


OBH 


OCH 


td 
RESET DISK macro 


mov ah,0ODH 
int 21H 
endm 


SELECT DISK macro disk 


; 
OPEN 


mov d1,disk[-65] 


Mov ah, OEH 
int 21H 
endm 


macro fcb 


mMOv dx,offset fcb 
mov ah,OFH 

int 21H 

endm 


CLOSE macro- fcb 


mov dx,offset fcb 
mov ah, 10H 

int 21H 

endm 


SEARCH FIRST macro fcb 


MOV dx,offset fcb 
MOV ah,1l1H 

int 21H 

endm 


; 
SEARCH NEXT macro fcb 


MOV dx,offset fcb 
MOV ah,12H 

int 21H 

endm 


DELETE macro- fcb 


e 
? 


mov dx,offset fcb 
mov ah,13H 

int 21H 

endm 


READ SEQ macro fcb 


mov dx,offset fcb 
mov ah, 14H 

int 21H 

endm 


; 
WRITE SEQ macro fcb 


mov dx,offset fcb 
mov ah, 15H 
int 21H 


endm 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 
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ODH 


OEH 


OFH 


LOH 


11H 


12H 


13H 


14H 


15H 


CREATE Macro fcb 


MOV 
mov 
int 
endm 


RENAME macro 


mov 
mov 
int 
endm 


dx,offset fcb 


ah,16H 
21H 


fcb,newname 


dx,offset fcb 


ah,17H 
21H 


CURRENT DISK macro 


Mov 
int 


endm 


SET DTA macro. buffer 
dx,offset buffer 


MOV 
mov 
endm 


° 
a 


IEF DRIVE DATA macro 


mov 
int 
endm 


UU 
DRIVE_DATA 


mov 
mov 
int 
endm 

ti 

READ RAN 
mov 
mov 
int 
endm 

a 

WRITE RAN 
‘MOV 
MOV 
int 
endm 


7 
FILE SIZE 
~ MOV 
MOV 
int 
endm 


ah, 19H 
21H 


ah, 1AH 


ah, 1BH 
21H 


d1l,drive 
ah, 1CH 
21H 


macro fcb 
dx offset 


ah,21H 
21H 


macro fcb 


dx,offset 
ah,22H 
21H 


macro fcb 


dx,offset 
ah, 23H 
21H 


macro drive 


fcb 


fcb 


fcb 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 
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16H 


17H 


19H 


LAH 


1BH 


1CH 


21H 


22H 


23H 
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; FUNCTION REQUEST 24H 
SET RELATIVE RECORD macro fcb 


mov dx,offset fcb 
mov ah,24H 

int 21H 

endm 


: FUNCTION REQUEST 25H 
SET VECTOR macro interrupt,handler start 


mov al,interrupt 

mov dx,offset handler start 
mov ah,25H 

int 21H 

endm 


; FUNCTION REQUEST 26H 
CREATE PSP macro seg addr 


MOV dx,offset seg addr 
mov ah, 26H 

int 21H 

endm 


; FUNCTION REQUEST 27H 
RAN BLOCK READ macro fcb,count,rec size 


Mov dx,offset fcb 

mov cx,count 

MOV word ptr fcb[14],rec_size 
MOV ah,27H 

int 21H 

endm 


; FUNCTION REQUEST 28H 
RAN BLOCK WRITE macro fcb,count,rec size 


MOV dx,offset fcb 

mov cx,count - 

mov word ptr fcb[14],rec_ size 
mov ah,28H 

int 21H 

endm 


; FUNCTION REQUEST 29H 
PARSE macro’ string,fcb 


Mov si,offset string 
mov di,offset fcb 
push es 

push ds 

pop es 

mov al,OFH 

mov ah, 29H 

int 21H 

pop es 

endm 


. FUNCTION REQUEST 2AH 
GET DATE macro 

mov ah, 2AH 

int 21H 

endm 
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; FUNCTION REQUEST 2BH 
SET DATE macro year,month,day 


mov ecx,year 
MOV dh,month 
mMOv dl1,day 
mov ah, 2BH 
int 21H 
endm 
: FUNCTION REQUEST 2CH 
GET TIME macro 
mov ah, 2CH 
int 21H 
endm 


; FUNCTION REQUEST 2DH 
SET TIME macro hour,minutes,seconds,hundredths 


mov ch,hour 

mov cl,minutes 
MOV dh,seconds 
MOV dl,hundredths 
MOV ah, 2DH 

int 21H 

endm 


. FUNCTION REQUEST 2EH 
VERIFY macro switch 


mov al,switch 
MOV ah, 2EH 
int 21H 

endm 


; FUNCTION REQUEST 2FH 
GET DTA macro 


MOV ah, 2FH 
int 21H 
endm 


; FUNCTION REQUEST 30H 
GET VERSION macro 


mov ah,30H 
int 21H 
endm 


: FUNCTION REQUEST 31H 
KEEP PROCESS macro return _code,last_ byte 


mov al,return_ code 

mov dx,offset last byte 
mov c1,4 

shr dx,cl 

inc dx 

MOV ah,31H 

int 21H 

endm 


; FUNCTION REQUEST 33H 
CTRL_C_CK macro action,state 


MOV al,action 
mov d1l,state 
mMOv ah,33H 
int 21H 


GET VECTOR 


Macro interrupt 
MOV al,interrupt 
mov ah,35H 
int 21H 


endm 


; 
GET DISK SPACE macro drive 
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FUNCTION REQUEST 35H 


FUNCTION REQUEST 36H 


mov dl,drive 
mov ah,36H 
int 21H 
endm 
: FUNCTION REQUEST 38H 
G=T COUNTRY macro country,buffer 
- local gc 01 
mv dx,offset buffer 
mov ax,country 
cmp ax,OFFH 
j1 gc_01 
mov al,Offh 
mov bx,country 
gc Ol: MOv ah, 38H 
int 21H 
endm 
: FUNCTION REQUEST 38H 
SET COUNTRY macro country 
local sc_01 
mov dx, OFFFFH 
mov ax,country 
cmp ax, OFFH 
jl sc_01 
mov al,Offh 
MOV bx,country 
sc Ol: mov ah, 38H 
int 21H 
endm 
: FUNCTION REQUEST 39H 
MAKE DIR macro path 
MOV dx,offset path 
mov ah,39H 
int 21H 
endm 


; 
REM DIR macro path 


mov dx,offset path 
Mov ah, 3AH 

int 21H 

endm 


; 
CHANGE DIR macro path 


mov dx,offset path 
mov ah, 3BH 
int 21H 


endm 


FUNCTION REQUEST 3AH 


FUNCTION REQUEST 3BH 
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; FUNCTION REQUEST 3CH 
CREATE HANDLE macro path,attrib 
MOV dx,offset path 


Mov cx,attrib 
Mov ah,3CH 
int 21H 

endm 


7 FUNCTION REQUEST 3DH 
OPEN HANDLE macro path,access 
mov dx,offset path 


Mov al,access 
MOV ah, 3DH 
int 21H 

endm 


; FUNCTION REQUEST 3EH 
CLOSE HANDLE macro handle 


mov bx,handle 
MOV ah,3EH 
int 21H 

endm 


: FUNCTION REQUEST 3FH 
READ HANDLE macro handle,buffer,bytes 


mov bx,handle 

MOV dx,offset buffer 
mov cx,bytes 

MOV ah, 3FH 

int 21H 

endm 


: FUNCTION REQUEST 40H 
WRITE HANDLE macro  handle,buffer,bytes 


MOV bx,handle 

MOV dx, ,offset buffer 
MOV cx,bytes 

MOV ah, 40H 

int 21H 

endm 


7 FUNCTION REQUEST 41H 
DELETE ENTRY macro path 
MOV dx,offset path 


mov ah,41H 
int 21H 
endm 


: FUNCTION REQUEST 42H 
MOVE PTR macro handle,high,low,method 


mov bx,handle 
mov cx,high 
Mov dx,low 
mov al,method 
MOV ah,42H 
int 21H 


? 
CHANGE MODE macro 


mov 
mov 
mv 
mv 
int 
endm 


a 

IOCTL DATA 
mov 
Mv 
mOv 
int 
endm 


IOCTL CHAR 
mov 
mov 
mov 
mov 
int 
endm 


dx,offset path 
al,action 
cx,attrib 
ah,43H 

21H 


Macro code,handle 
bx, handle 

al,code 

ah,44H 

21H 


macro 
bx,handle 
dx,offset buffer 
al,code 

ah,44H 

21H 


FUNCTION 


path,action,attrib 


FUNCTION 


FUNCTION 


code ,handle,buffer 


FUNCTION 


IOCTL STATUS macro  code,drive,buffer 


mov 
mov 
mov 
MOV 
int 
endm 


a 

IOCTL BLOCK 
mov 
mov 
mov 
int 
endm 


bl,drive 
dx,offset buffer 
al,code 

ah, 44H 

21H 


macro code,handle 
bx,handle 

al,code 

ah, 44H 

21H 


; 
IOCTL CHANGE macro drive 


mov 
mov 
mov 
int 
endm 


bl,drive 


al,0O8H 
ah,44H 
21H 


IOCTL RBLOCK macro drive 


mov 
mov 
mov 
int 
endm 


bl,drive 


al,09H 


ah, 44H 


21H 


FUNCTION 


FUNCTION 


FUNCTION 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 
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43H 


4400H,01H 


4402H,03H 


4404H,05H 


4406H,07H 


4408H 


4409H 


7 
IOCTL RHANDLE macro handle 


MOV 
mov 
Mov — 
int 
endm 


t 

IOCTL RETRY 
mov 
mov 
MOV 
mOv 
int 
endm 


=e 


XDUP macro 
mov 
int 
endm 


bx ,yhandle 
al ,0OAH 

ah ,44H 
21H 


Macro retries,wait 
bx,retries 

cx ,wait 

al,0OBH 

ah,44H 

21H 


handle 
bx,handle 
ah,45H 
21H 


XDUP2 macro handlel,handle2 


mov 
mov 
mov 
int 
endm 


bx, handlel 
cx,handle2 
ah, 46H 

21H 


; 
GET DIR macro drive,buffer 


mov 
mov 
Mov 
int 
endm 


d1l,drive 
si,offset buffer 
ah,47H 

21H 


; 
ALLOCATE MEMORY macro bytes 


mov 
mov 
shr 
inc 
mov 
int 
endm 


a 

FREE MEMORY 
Mov 
MOv 
MOV 
int 
endm 


macro seg addr 
ax,seg_ addr 
es,ax 

ah,49H 

21H 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 
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REQUEST 440AH 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


440BH 


45H 


46H 


47H 


48H 


49H 


a 
SET BLOCK 
~ mov 
mov 
shr 
add 
Mov 
int 
mov 
shl 
Mov 
mov 
endm 


° 
a 
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FUNCTION REQUEST 4AH 


macro last byte 

bx,offset last byte 
c1,4 _ 
bx,cl 
bx,17 

ah, 4AH 

21H 

ax,bx 

ax,cl 

sp,ax 

bp,sp 


FUNCTION REQUEST 4B0O0H 


EXEC macro path,command,parms 


mov 
mov 


Mov 
int 
endm 


a 

EXEC _OVL 
MOV 
mov 
mov 
mov 
Mov 
MOv 
int 
endm 


END PROCES 


=e 


dx,offset path 
bx,offset parms 

word ptr parms[02h] ,offset command 
word ptr parms[04h],cs 
word ptr parms[06h] ,5ch 
word ptr parms[08h],es 
word ptr parms[0Oah],6ch 
word ptr parms[0Och],es 
al,0 

ah, 4BH 

21H 


FUNCTION REQUEST 4B03H 


macro path,parms,seg addr 
dx,offset path 
bx,offset parms 
parms,seg_ addr 
parms [02H] ,seg_ addr 
al,3 
ah, 4BH 
21H 


FUNCTION REQUEST 4CH 


S macro return code 


MOV al,return_code 
mov ah, 4CH 

int 21H 

endm 


FUNCTION REQUEST 4DH 


WAIT macro 


mov 
int 
endm 


mov 
mov 
mov 
int 
endm 


ah, 4DH 
21H 


dx,offset path 
cx,attrib 

ah, 4EH 

21H 


; FUNCTION REQUEST 4EH 
FIND FIRST FILE macro path,attrib 
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; FUNCTION REQUEST 4FH 
FIND NEXT FILE macro 


MOV ah, 4FH 
int 21H 
endm 


. FUNCTION REQUEST 54H 
GET VERIFY macro 


mov ah,54H 
int 21H: 
endm 


; FUNCTION REQUEST 56H 
RENAME FILE macro old path,new path 
MOV dx,offset old path 


push ds 

pop es 

mov di,offset new_path 
mov ah ,56H 

int 21H 

endm 


: FUNCTION REQUEST 57H 
GET SET DATE TIME macro handle,action,time,date 


MOv bx, handle 

MOV al,action 

MOV cx,word ptr time 
mov dx,word ptr date 
MOV ah,57H 

int 21H 

endm 


; FUNCTION REQUEST 58H 
ALLOC_STRAT macro code,strategy 


MOV bx,strategy 
Mov al,code 

mMOv ah,58H 

int 21H 

endm 


7 FUNCTION REQUEST 59H 
GET ERROR macro 


Mov ah,59 
int 21H 
endm 


7 FUNCTION REQUEST 5AH 
CREATE TEMP macro pathname,attrib 


mov cx,attrib 

mov dx,offset pathname 
mov ah, 5AH 

int 21H 

endm 


; FUNCTION REQUEST 5BH 
CREATE NEW macro pathname,attrib 


mOv cx,attrib 

MOV dx,offset pathname 
mov ah,5BH 

int 21H 


endm 


=e 


LOCK 


UNLOCK 


GET MACHINE NAME macro. buffer 


e 


mov 
Mov 
mov 
mov 
int 
endm 


macro 
mv 


mov 
int 
endm 


MOV 
mov 
mov 
int 
endm 
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FUNCTION REQUEST 5C0O0H 
handle,start,bytes 
bx handle 
cx,word ptr start 
dx,word ptr start+2 
Si,word ptr bytes 
di,word ptr bytes+2 


al,0 
ah ,5CH 
21H 
FUNCTION REQUEST 5CO0O1H 
handle,start,bytes 
bx, handle 


cx,word ptr start 
dx,word ptr start+2 
si,word ptr bytes 
di,word ptr bytes+2 
al,l 

ah,5CH 

21H 


FUNCTION REQUEST 5E00H 
dx,offset buffer 
al,0 


ah, 5EH 
21H 


FUNCTION REQUEST 5E02H 


a 
PRINTER SETUP macro index,lgth,string 


; 
GET LIST 


mov 
mov 
mov 
mov 
mov 
int 
endm 


macro 


bx, index 

cx,lgth 
dx,offset string 
al,2 

ah,5EH 

21H 


FUNCTION REQUEST 5F02H 
index, local,remote 
bx, index 
si,offset local 
di,offset remote 
al,2 
ah, 5FH 
21H 
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: FUNCTION REQUEST 5F03H 
REDIR macro local,remote,device,value 

mov bl,device 

mov cx,value 

mov si,offset local 

mMOv di,offset remote 

mov al,3 

mov ah,5FH 

int 21H 

endm 


; FUNCTION REQUEST 5F04H 
CANCEL REDIR macro local 


MOV si,offset local 
mov al,4 
mov ah,5FH 
int 21H 
endm 
; FUNCTION REQUEST 62H 
GET PSP macro 
a mov ah ,62H 
int 21H 
endm 


? 

7 

eREKKEKEKEKKEKEEKRKEKEKKE 

s General 

eRRKKKEKEEEKEEKEKEEKK 

H 

DISPLAY_ASCIIZ macro asciiz string 
local search,found it 


mov bx,offset asciiz string 
search: 

cmp byte ptr [bx] ,0 

je found_it 

inc bx 


jmp short search 


found it: 
mov byte ptr [bx],"$" 
display asciiz string 
mov byte ptr [bx] ,0 
display char ODH 
display char OAH 
endm 


, 
MOVE STRING macro source,destination,count 


push 
push 


pop 
assume 


rep movs 
assume 


pop 
endm 


es 

ds 

es 

es: code 

si,offset source 
di,offset destination 
cx,count 
es:destination,source 
es:nothing 

es 


; 
CONVERT macro value,base,destination 


local 
jmp 
table db 


start: 
push 
push 
push 
mov 
xOr 
XOX 


table,start 
Start 
"0123456789ABCDEF" 


ax 

bx 

dx 

al,value 

ah,ah 

bx, bx 

base 

bl,al 
al,cs:table[bx] 
destination,al 
bl,ah 

al,cs: table [bx] 
destination[l],al 
dx 

bx 

ax 


7 
CONVERT TO BINARY macro. string,number,value 


local 
jmp 
ten db 


starts: 
mov 


ten,start,calc,mult,no mult 
start 
10 


value,0 
Cx Cx 
cl,number 
si,si 
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ax,ax 
al,string[si] 
al,48 

Cx; 2 

no mult 

cx 

cx 


cs: ten 
mult 
cx 


value,ax 
si 
calc 


7 
CONVERT DATE macro dir _ entry 


mov 
mov 
shr 
MOv 
and 
XOr 
mov 
shr 
add 
endm 


PACK DATE 


dx,word ptr dir _entry[24] 
cl,5 

di,cl 

dh,dir_entry[24] 

dh, 1FH 

Cx,Cx 

cl,dir entry[25] 

CL, 

cx,1980 


Macro date 


~ local set_bit 


me BO WE 


sub 
push 
MOV 
mov 
shl 
Pop 
jnc 
or 


set bit: 
~ or 
rol 
mov 
endm 


=e 


On entry: DH=day, DL=month, CX=(year-1980) 


cx,1980 
Cx 
date,dh 
cl1,5 
dl,cl 
Cx 
set_bit 
cl1,80h 


date,dl 
cl1l,l 
date[1l],cl 
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CHAPTER 2 


MS-DOS DEVICE DRIVERS 


2.1 INTRODUCTION 


The I0.SYS file is composed of the "resident" device 
drivers. This forms the MS-DOS BIOS, and these drivers are 
called upon by MS-DOS to handle I/O requests initiated by 
application programs. 


One of the most powerful features of MS-DOS is the ability 
to add new devices such as printers, plotters, or mouse 
input devices without rewriting the BIOS. The MS-DOS’ BIOS 
is "configurable;" that is, new drivers can be added and 
existing drivers can be pre-empted. Non-resident device 
drivers may be easily added by an end user at boot time via 
the "DEVICE =" entry in the CONFIG.SYS file. In this 
section, these non-resident drivers are termed "installable" 
to distinguish them from drivers in the I0.SYS file, which 
are considered the resident drivers. 


At boot time, a minimum of five resident device drivers must 
be present. These drivers are in a linked list: the 
"header" of each one contains a DWORD pointer to the next. 
The last driver in the chain has an end-of-list marker of 
-1, -1l (all bits on). 


Each driver in the chain has two entry points: the strategy 
entry point and the interrupt entry point. MS-DOS does not 
take advantage of the two entry points: it calls the 
Strategy routine, then immediately calls the interrupt 
routine. 


The dual entry points facilitate future multitasking 
versions of MS-DOS. In multitasking environments, I/O must 
be asynchronous; to accomplish this, the strategy routine 
will be called to (internally) queue a request and return 
quickly. It is then the responsibility of the interrupt 
routine to perform the I/O at interrupt time by getting 
requests from the internal queue and processing them. When 
a request is completed, it is flagged as "done" by the 
interrupt routine. MS-DOS periodically scans the list of 
requests looking for those that are flagged as done, and 
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"wakes up" the process waiting for the completion of the 
request. 


When requests are queued in this manner, it is no longer 
sufficient to pass I/O information in registers, since many 
requests may be pending at any time. Therefore, the MS-DOS 
device interface uses "packets" to pass request information. 
These request packets are of variable size and format, and 
are composed of two parts: 


1. The static request header section, which has_ the 
same format for all requests. 


2. A section which has information specific to the 
type of request. 


A driver is called with a pointer to a packet. In 
multitasking versions, this packet will be linked into a 
global chain of all pending I/O requests maintained by 
MS-DOS. 


MS-DOS does not implement a global or local queue. Only one 
request is pending at any one time. The strategy routine 
must store the address of the packet at a fixed location, 
and the interrupt routine, which is called immediately after 
the strategy routine, should process the packet by 
completing the request and returning. It is assumed that 
the request is completed when the interrupt routine returns. 


To make a device driver that SYSINIT can install, a_.BIN 
(core image) or .EXE format file must be created with the 
device driver header at the beginning of the file. The link 
field should be initialized to -1 (SYSINIT fills it in). 
Device drivers which are part of the BIOS should have their 
headers point to the next device in the list and the last 
header should be initialized to -1,-l1. The BIOS must be a 
-BIN (core image) format file. 


-EXE format installable device drivers may be used in 
non-IBM versions of MS-DOS. On the IBM PC, the .EXE loader 
is located in COMMAND.COM which is not present at the time 
that installable devices are being loaded. 


2.2 FORMAT OF A DEVICE DRIVER 


A device driver is a program segment responsible _ for 
communication between DOS and the system hardware. It has a 
special header at the beginning identifying it as a device 
driver, defining entry points, and describing various 
attributes of the device. 


a 


_ 


MS-DOS DEVICE DRIVERS Page 2-3 


Note 


For device drivers, the file must not use the ORG 100H 
(like .COM files). Because it does not use the Program 


Segment Prefix, the device driver is simply loaded; 
therefore, the file must have an origin of zero (ORG 0 
or no ORG statement). 


There are two kinds of device drivers: 
1. Character device drivers 
2. Block device drivers 


Character devices perform serial character I/0. Examples 
are the console, communications port and printer. These 
devices are named (i.e., CON, AUX, CLOCK, etc.), and 
programs may open channels (handles or FCBs) to do I/O to 
them. 


Block devices are the "disk drives" on the system. They can 
perform random I/0 in structured pieces called blocks 
(usually the physical sector Size). These devices are not 
named as the character devices are, and therefore cannot be 
opened directly. Instead they have unit numbers’ and are 
identified by driver letters such as A, B, and C. 


A single block-device driver may be responsible for one or 
more logically contiguous disk drives. For example, block 
device driver ALPHA may be responsible for drives A, B, C, 
and D. This means that it has four units defined (0-3), and 
therefore, takes up four drive letters. The position of the 
driver in the list of all drivers determines which units 
correspond to which driver letters. If driver ALPHA is’ the 
first block driver in the device list, and it defines 4 
units (0-3), then they will be A, B, C, and D. If BETA is 
the second block driver and defines three units (0-2), then 
they will be E, F, and G, and so on. The theoretical limit 
is 63, but it should be noted that the device installation 
code will not allow the installation of a device if it would 
result in a drive letter >'Z' (5AH). All block device 
drivers present in the standard resident BIOS will be placed 
ahead of installable block-device drivers in the list. 


Note 


Character devices cannot define multiple units 
because they have only one name. 
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2.3 HOW TO CREATE A DEVICE DRIVER 


To create a device driver that MS-DOS can install, you must 
create a binary file (.COM or .EXE format) with a device 
header at the beginning of the file. Note that for device 
drivers, the code should not be originated at 100H, but at 
0. The device header contains a link field (pointer to next 
device header) which should be -1, unless there is more than 
one device driver in the file. The attribute field and 
entry points must be set correctly. 


If it is a character device, the name field should be filled 
in with the name of that character device. The name can be 
any legal 8-character filename. If the name is less’ than 
eight characters, it should be padded out to eight 
characters with spaces (20H). Note that device names do not 
include colons (:). The fact that "CON" is the same as 
"CON:" is a property of the default MS-DOS command 
interpreter (COMMAND.COM) and not the device driver or the 
MS-DOS interface. All character device names are handled in 
this way. 


MS-DOS always processes installable device drivers’ before 
handling the default devices, so to install a new CON 
device, simply name the device "CON". Remember to set’ the 
Standard input device and standard output device bits in the 
attribute word on a new CON device. The scan of the device 
list stops on the first match, so the installable device 
driver takes precedence. 


It is not possible to replace the "resident" disk block 
device driver with an installable device driver the same way 
you can replace the other device drivers in the BIOS. Block 
drivers can be used only for devices not directly supported 
by the default disk drivers in I0.SYS. 


Note 


Because MS-DOS can install the driver anywhere in 


memory, care must be taken when making far memory 
references. You should not expect that your driver 
will always be loaded in the same place every time. 
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2.3.1 Device Strategy Routine 


This routine, which is called by MS-DOS for each device 
driver service request, is primarily responsible for queuing 
these requests in the order in which they are to. be 
processed by the Device Interrupt Routine. Such queuing can 
be a very important performance feature in a multitasking 
environment, or where asynchronous I/0 is supported. As 
MS-DOS does not currently Support these facilities, only one 
request can be serviced at a time, and this routine is 
usually very short. In the coding examples in Section 2.12, 
each request is simply stored in a Single pointer area. 


2.3.2 Device Interrupt Routine 


This routine contains all of the code to process the service 
request. Tt may actually interface to the hardware, or it 
may use ROM BIOS calls. It usually consists of a series of 
procedures which handle the specific command codes to be 
Supported as well as some exit and error-handling routines. 
See the coding examples in Section 2.12. 


2.4 INSTALLATION OF DEVICE DRIVERS 

MS-DOS allows new device drivers to be installed dynamically 
at boot time. This is accomplished by initialization code 
in IO.SYS which reads and processes the CONFIG.SYS file. 
MS-DOS calls upon the device drivers to perform their 
function in the following manner: 


1. MS-DOS makes a far call to Strategy entry. 


2. MS-DOS passes device driver information in a 
request header to the strategy routine. 


3. MS-DOS makes a far call to the interrupt entry. 


This structure is designed to be easily upgraded to support 
any future multitasking environment. 
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2.5 DEVICE HEADERS 


A device header is required at the beginning of a device 
driver. A device header looks like this: 


DWORD Pointer to next device 
(Usually set to -l if this driver 
is the last or only driver in the 
file) 


WORD Attributes 
Bit 15 if character device 
if block device 
if IOCTL supported 
if output till busy 
(character devices) 
1 if NON FAT ID 
(block devices) 
reserved (must be 0) 
1 if support OPEN/CLOSE/RM 
reserved (must be 0) 
1 if intended current CLOCK 
device 
1 if intended current NUL 
device 
1 if intended current sto 
device 
1 if intended current sti 
device 


WORD Pointer to device strategy 
entry point 

WORD Pointer to device interrupt 
entry point 


8-BYTE Character device name field 
Character devices set a device name. 
For block devices the first byte is 
the number of units. 


Bit 14 
Bit 13 


Figure 2.1 Sample Device Header 


Note that the device entry points are words. They must be 
offsets from the same segment number used to point to this 
table. For example, if XXX:YYY points to the start of this 
table, then XXX:strategy and XXXs:interrupt are the entry 
points. 


The device header fields are described in the following 
section. 
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2.5.1 Pointer to Next Device Field 


The pointer to the next device header field is a double word 
field (offset followed by segment) that is set by MS-DOS to 
point at the next driver in the system list at the time the 
device driver is loaded. It is important that this field be 
set to -l prior to load (when it is on the disk as a file) 
unless there is more than one device driver in the file. If 
there is more than one driver in the file, the first word of 
the double word pointer should be the offset of the next 
driver's device header. 


Note 


If there is more than one device driver in the, 


file, the last driver in the file must have the pointer 
to the next device header field set to -l. 


2.5.2 Attribute Field 


The attribute field is used to identify the type of device 
this driver is responsible for. In addition to 
distinguishing between block and character devices, these 
bits are used to give selected character devices special 
treatment. (Note that if a bit in the attribute word is 
defined only for one type of device, a driver for the other 
type of device must set that bit to 0.) 


For example, assume that a user has a new device driver that 
he wants to use as the Standard input and output. In 
addition to installing the driver, he must tell MS-DOS that 
he wants his new driver to override the current standard 
input and standard output (the CON device). This is 
accomplished by setting the attributes to the desired 
characteristics, so he would set bits 0 and 1 to 1 £(note 
that they are separate!). Similarly, a new CLOCK device 
could be installed by setting that attribute. (Refer to 
Section 2.10, "The CLOCK Device," in this chapter for more 
information.) Although there is a NUL device attribute, the 
NUL device cannot be reassigned. This attribute exists so 
that MS-DOS can determine if the NUL device is being used. 


The NON FAT ID bit for block devices affects the operation 
of the BUILD BPB (BIOS Parameter Block) device call. The 
NON FAT ID bit has a different meaning on character devices. 
It indicates that the device implements the OUTPUT UNTIL 
BUSY device call. 


The IOCTL bit has meaning on character and block devices. 
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The IOCTL functions allow data to be sent and received by 
the device for its own use (for example, to set baud rate, 
stop bits, and form length), instead of passing data over 
the device channel as does a normal read or write. The 
interpretation of the passed information is up to the 
device, but it must not be treated as a normal I/O request. 

This bit tells MS-DOS whether the device can handle control 

strings via the IOCTL system call, Function 44H. 


Tf a driver cannot process control strings, it should 
initially set this bit to,0. This tells MS-DOS to return an 
error if an attempt is made (via Function 44H) to send or 
receive control strings to this device. A device which can 
process control strings should initialize the IOCTL bit to 
i. For drivers of this type, MS-DOS will make calls to the 
IOCTL INPUT and OUTPUT device functions to send and receive 
IOCTL strings. 


The OPEN/CLOSE/RM bit signals to MS-DOS 3.x and =Ilater 
versions whether this driver supports additional MS-DOS 3.0 
functionality. To support these old drivers, it is 
necesSary to detect them. This bit was reserved in MS-DOS 
2.x, and is 0. All new devices should support the OPEN, 
CLOSE, and REMOVABLE MEDIA calls and set this bit to l. 
Since MS-DOS 2.x never makes these calls, the driver will be 
backward compatible. 


2.5.3 Strategy And Interrupt Routines 


These two fields are the pointers to the entry points of the 
strategy and interrupt routines. They are word values, so 
they must be in the same segment as the device header. 


2.5.4 Name Field 


This is an 8-byte field that contains the name of a 
character device or the number of units of a block device. 
If it is a block device, the number of units can be put in 
the first byte. This is optional, because MS-DOS will fill 
in this location with the value returned by the driver's 
INIT code. Refer to Section 2.4, "Installation of Device 
Drivers," for more information. 
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2.6 REQUEST HEADER 


When MS-DOS calls a device driver to perform a function, it 
passes a request header in ES:BX to the strategy entry 
point. This is a fixed length header, followed by data 
pertinent to the operation being performed. Note that it is 
the device driver's responsibility to preserve the machine 
State (for example, save all registers including flags on 
entry and restore them on exit). There is enough room. on 
the stack when strategy or interrupt is called to do about 
20 pushes. If more stack is needed, the driver should set 
up its own stack. 


The following figure illustrates a request header. 
REQUEST HEADER -> 
BYTE Length of record 


Length in bytes of this 
request header 


BYTE Unit code 
The subunit the operation 
is for (minor device) 
(no meaning on character 


devices) 


BYTE Command code 


WORD Status 


8 BYTES Reserved 


Figure 2.2 Request Header 


The request header fields are described below. 


2.6.1 Length of Record 


This field contains the length (in bytes) of the request 
header. 


2.6.2 Unit Code Field 


The unit code field identifies which unit in your device 
driver the request is for. For example, if your device 
driver has 3 units defined, then the possible values of the 
unit code field would be 0, 1, and 2. 
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2.6.3 Command Code Field 


The command code field in the request header can have the 
following values: 


Command Function 


Code 

0 INIT 

1 MEDIA CHECK (Block devices only) 

2 BUILD BPB * 

3 IOCTL INPUT (Only called if device has IOCTL) 

4 INPUT (read) 

5 NON-DESTRUCTIVE INPUT NO WAIT (Char Gove ha 

6 INPUT STATUS 

7 INPUT FLUSH " ” : 

8 OUTPUT (Write) 

9 OUTPUT (Write) with verify 
10 OUTPUT STATUS se = " 
ll OUTPUT FLUSH < y 
12 IOCTL OUTPUT (Only called if device has IOCTL) 

13 DEVICE OPEN (Only called if OPEN/CLOSE/RM bit set) 
14 DEVICE CLOSE (Only called if OPEN/CLOSE/RM bit set 
15 REMOVABLE MEDIA (Only called if OPEN/CLOSE/RM bit 
set and device is block) 

16 OUTPUT UNTIL BUSY (Only called if bit 13 is set on 


character devices) 


2.6.4 Status Field 


The following figure illustrates the status field in the 
request header. 


15 14131211410 9 8 7 6 5 4 3 2 1 =O 


RESERVED ERROR CODE (bit 15 on) 


The status word is zero on entry and is set by the driver 
interrupt routine on return. 


Bit 8 is the done bit. When set, it means the operation has 
completed. The driver sets it to 1 when it exits. 
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Bit 15 is the error bit. If it is set, then the low 8 bits 
indicate the error. The errors are: 


Write protect violation 
Unknown unit 

Drive not ready 

Unknown command 

CRC error 

Bad drive request structure length 
Seek error 

Unknown media 

Sector not found 
Printer out of paper 
Write fault 

Read fault 

General failure 
Reserved 

Reserved 

Invalid disk change 


YOmOuoUQWPO OAHU BWNHHEHO 


Bit 9 is the busy bit, which is set only by status calls and 
the removable media call. 


2.7 DEVICE DRIVER FUNCTIONS 
Device drivers may perform all or some of these nine general 
functions. In some cases, these functions break down into 
several command codes, for specific cases. Each is 
described in this section. 

1. INIT 

2. MEDIA CHECK 

3. BUILD BPB 


4. READ or WRITE or WRITE TIL BUSY or WRITE WITH 
VERIFY or IOCTL Read or IOCTL Write 


5. NON DESTRUCTIVE READ NO WAIT 
6. OPEN or CLOSE (3.x) 

7. REMOVABLE MEDIA (3.x) 

8. STATUS 

9. FLUSH 


All strategy routines are called with ES:BX pointing to the 
Request Header. The interrupt routines get the pointers to 
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the Request Header from the queue that the strategy routines 
store them in. The command code in the request header tells 
the driver which function to perform and what data follows 
the request header. 


Note 


All DWORD pointers are stored offset first, then 
segment. 


2.7.1 INIT 


Command code = 0 


INIT - ES:BX -> 


13-BYTE Request header 


BYTE Number of units 
DWORD End Address 


DWORD Pointer to BPB array 
(Not set by character devices) 
BYTE Block device number 


One of the functions defined for each device driver is INIT. 
This routine is called only once when the device is 
installed. The INIT routine must return the END ADDRESS, 
which is a DWORD pointer to the end of the portion of the 
device driver to remain resident. This pointer method can 
be used to delete initialization code that is only needed 
once, Saving space. 


The number of units, end address, and BPB pointer are to be 
set by the driver. However, on entry for installable device 
drivers, the DWORD that is to be set by the driver to. the 
BPB array (on block devices) points to the character after 
the "=" on the line in CONFIG.SYS that caused this device 
driver to be loaded. This allows drivers to scan the 
CONFIG.SYS invocation line for parameters which might be 
passed to the driver. This line is terminated by a Return 
or a Line Feed. This data is read-only and allows’ the 
device to scan the CONFIG.SYS line for arguments. 


MS-DOS DEVICE DRIVERS Page 2-13 


device=\dev\vt52.sys /l 
BPB address points here 


Also, for block devices only, the drive number assigned to 
the first unit defined by this driver (A=0) as contained in 
the block device number field. This is also read-only. 


For installable character devices, the end address parameter 
must be returned. This is a pointer to the first available 
byte of memory above the driver and may be used to_ throw 
away initialization code. 


Block devices must return the following information: 


1. The number of units must be returned. MS-DOS’ uses 
this to determine logical device names. If the 
Current maximum logical device letter is F at’ the 
time of the install call, and the INIT routine 
returns 4 as the number of units, then they will 
have logical names G, H, I and J. This mapping is 
determined by the position of the driver in the 
device list, and by the number of units on the 
device (stored in the first byte of the device name 
field). 


2. A DWORD pointer to an array of word offsets 
(pointers) to BPBs (BIOS Parameter Blocks) must be 
returned. The BPBS passed by the device driver are 
used by MS-DOS to create an internal structure. 
There must be one entry in this array for each unit 
defined by the device driver. In this way, if all 
units are the same, all of the pointers can point 
to the same BPB, Saving’ space. If the device 
driver defines two units, then the DWORD pointer 
points to the first of two one-word offsets which 
in turn point to BPBs. The format of the BPB is 
described later in this chapter in Section 2.7.3, 
"BUILD BPB." 


Note that this array of word offsets must be 
protected (below the free pointer set by the 
return) Since an internal DOS structure will be 
built starting at the byte pointed to by the free 
pointer. The defined sector size must be less than 
Or equal to the maximum sector size defined by the 


resident device drivers (BIOS) during 
initialization. If it isn't, the installation will 
fail. 


3. The last thing that INIT of a block device must 
pass back is the media descriptor byte. This byte 
means nothing to MS-DOS, but is passed to devices 
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so that they know what parameters MS-DOS is 
currently using for a particular drive unit. 


Block devices may be either dumb or smart. A dumb device 
defines a unit (and therefore an internal DOS structure) for 
each possible media-drive combination. For example, unit 0 
= drive 0 single sided, unit 1 = drive 0 double sided. For 
this approach, media descriptor bytes do not mean anything. 
A smart device allows multiple media per unit. In this 
case, the BPB table returned upon INIT must define 
sufficient space to accommodate the largest possible media 
Supported. Smart drivers will use the media descriptor byte 
to pass information about what media is currently in a unit. 


For more information on the media descriptor byte, see 
Section 2.8, "Media Descriptor Byte." 


Note 


If there are multiple device drivers in a single 
file, the ending address returned by the last INIT 
called will be the one MS-DOS uses. It is recommended 


that all of the device drivers in a single file 

return the same ending address. The code to remain 
resident for all the devices in a Single file should 
be grouped together low in memory with the initializa- 
tion code for all devices following it in memory. 


2.7.2 MEDIA CHECK 


Command Code = 1 


MEDIA CHECK - ES:BX -> 


Returned DWORD pointer to previous 
Volume ID if bit 11 set and 
Disk Changed is returned 


Pe 
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The MEDIA CHECK function is used with block devices’ only. 
It is called when there is a pending drive access call other 
than a file read or write, such as open, close, delete and 
rename. Its purpose is to determine whether the media in 
the drive has been changed. If the driver can asSure_ that 
the media has not been changed (through a door-lock or other 
interlock mechanism), MS-DOS performance is enhanced because 
MS-DOS does not need to reread the FAT and invalidate 
in-memory buffers for each directory access. 


When such a disk access call to the DOS occurs (other than a 
file read or write), the following sequence of events takes 
place: 


Ll. The DOS converts the drive letter into a unit 
number of a particular block device. 


2. The device driver is then called to request a media 
check on that subunit to see if the disk might have 
been changed. MS-DOS passes the old media 
descriptor byte. The driver returns: 


Media not changed...... (1) 
Don't know if changed... (0) 
Media changed...........- (Ll) 
Error 


If the media has not been changed, MS-DOS proceeds 
with the disk access. 


If the value returned is "Don't know," then if 
there are any disk sectors that have been modified 
and not written back out to the disk yet for this 
unit, MS-DOS assumes that the disk has not been 
changed and proceeds. MS-DOS invalidates any other 
buffers for the unit and does a BUILD BPB device 
call (see step 3, below). 


If the media has been changed, MS-DOS invalidates 
all buffers associated with this unit including 
buffers with modified data that are waiting to be 
written, and requests a new BIOS Parameter Block 
via the BUILD BPB call (see step 3, below). 


3. Once the BPB has been returned, MS-DOS corrects its 
internal structure for the drive from the new BPB 
and proceeds with the access after reading’ the 
directory and the FAT. 


Note that the previous media ID byte is passed to the device 
driver. If the old media ID byte is the same as the new 
one, the disk might have been changed and a new disk may _ be 
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in the drive; therefore, all FAT, directory, and data 
sectors that are buffered in memory for the unit are 
considered to be invalid. 


If the driver has bit 11 of the device attribute word set to 
1, and the driver returns -l1, Media Changed, the driver must 
set the DWORD pointer to the previous Volume ID field. Tf 
the DOS determines that Media Changed is an error based on 
the state of the DOS buffer cache, the DOS will generate a 
OFH error on behalf of the device. If the driver does not 
implement Volume ID support, but has bit 11 set, (it should 
set a static pointer to the string "NO NAME",0.) 


A creative solution to the problem of no door-locks follows: 


It has been determined that it is impossible for a user to 
change a disk in less than 2 seconds; therefore, when MEDIA 
CHECK occurs within 2 seconds of a disk access, the driver 
reports "1," "Media not changed." This makes a tremendous 
improvement in performance. 


Note 


If the media ID byte in the returned BPB is the same as 
the previous media ID byte, MS-DOS will assume that the 


format of the disk is the same (even though the disk 

may have been changed) and will skip the step of up- 
dating its internal structure. Therefore, all BPBS must 
have unique media bytes regardless of FAT ID bytes. 


MS-DOS DEVICE DRIVERS Page 2-17 


2.7.3 BUILD BPB (BIOS Parameter Block) 


Command code = 2 


BUILD BPB - ES:BX -> 


DWORD Transfer address 
(Points to one sector worth of 


scratch space or first sector 

of FAT depending on the value 

of Bit 13 in the device attribute 
word.) 


' DWORD Pointer to BPB 


The Build BPB function is used with block devices only. As 
described in the MEDIA CHECK function, the BUILD  BPB 
function will be called any time that a preceding MEDIA 
CHECK call indicates that the disk has been or might have 
been changed. The device driver must return a pointer to a 
BPB. This is different from the INIT call where a pointer 
to an array of word offsets to BPBs is returned. 


The BUILD BPB call gets a DWORD pointer to a one-sector 
buffer. The contents of this buffer are determined by the 
NON FAT ID bit (bit 13) in the attribute field. If the bit 
is zero, then the buffer contains the first sector of the 
first FAT. The FAT ID byte is the first byte of this 
buffer. In this case, the driver must not alter this 
buffer. Note that the location of the FAT must be the- same 
for all possible media because this first FAT sector must be 
read before the actual BPB is returned. If the NON FAT ID 
bit is set, then the pointer points to one sector of scratch 
space (which may be used for anything). Refer to Section 
2.8, "Media Descriptor Byte,"" and Section 2.9, "Format of a 
Media Descriptor Table," for information on how to construct 
the BPB. 


MS-DOS 3.x includes additional support for devices that have 
door-locks or some other means of telling when a disk has 
been changed. There is a new error that can be returned 
from the device driver (error 15). The error means "the 
disk has been changed when it shouldn't have been," and the 
user iS prompted for the correct disk using a Volume ID. 
The driver may generate this error on read or write. The 
DOS may generate the error on MEDIA CHECK if the driver 
reports media changed, and there are buffers in the _ DOS 
buffer cache that need to be flushed to the previous disk. 
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For drivers that support this error, the BUILD BPB- function 
is a trigger that causes a new Volume ID to be read off the 
disk. This action indicates that the disk has been legally 
changed. A Volume ID is’ placed on a disk by the FORMAT 
utility, and is simply an entry in the root directory of the 
disk that has the Volume ID attribute. It is stored by the 
driver as an ASCIZ string. \ 


The requirement that the driver return a Volume ID does. not 
exclude some other Volume identifier scheme as long as the 
scheme uses ASCIZ strings. A NUL (nonexistent or 
unsupported) Volume ID is by convention the String: 


DB "NO NAME ",0 


2.7.4 READ or WRITE 


Command codes = 3,4,8,9, 12, and 16 


READ OR WRITE (Including IOCTL) or 
OUTPUT UNTIL BUSY - ES:BX -> 


Returned DWORD pointer to requested 
Volume ID if error OFH 


COMMAND CODE REQUEST 


IOCTL READ 

READ (block or character) 

WRITE (block or character) 

WRITE WITH VERIFY 

IOCTL WRITE 

OUTPUT TIL BUSY (char devs only) 


COV NO Oo CO & W 


wall oe 


The driver must perform the READ or WRITE call depending on 
which command code is_ set. Block devices read or write 
sectors; character devices read or write bytes. ( 
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When I/O completes, the device driver must set the status 
word and report the number of sectors or bytes successfully 
transferred. This should be done even if an error prevented 
the transfer from being completed. Setting the error bit 
and error code alone is not sufficient. 

In addition to setting the status word, the driver must. set 
the sector count to the actual number of sectors (or bytes) 
transferred. No error check is performed on an IOCTL I/0 
call. The device driver must always set the return 
byte/sector count to the actual number of bytes/sectors 
successfully transferred. 


If the verify switch is on, the device driver will be called 
with command code 9 (WRITE WITH VERIFY). Your device driver 
will be responsible for verifying the write. 


If the driver returns error code OFH (Invalid disk change), 
it must return a DWORD pointer to an ASCIZ string (which is 
the correct Volume ID). Returning this error code triggers 
the DOS to prompt the user to re-insert the disk. The 
device driver should have read the Volume ID as a result of 
the BUILD BPB function. 


Drivers may maintain a reference count of open files on the 
disk by monitoring the OPEN and CLOSE functions. This 
allows the driver to determine when to return error OFH. If 
there are no open files (reference count = 0), and the disk 
has been changed, the I/O is okay. If there are open files, 
however, an OFH error may exist. 


The OUTPUT UNTIL BUSY call is a speed optimization on 
character devices only for print  spoolers. The device 
driver is expected to output all the characters possible 
until the device returns’ busy. Under no circumstances 
should the device driver block during this function. Note 
that it is not an error for the device driver to return the 
number of bytes output being less than the number of bytes 
requested (or = 0). 


The OUTPUT UNTIL BUSY call allows spooler programs to take 
advantage of the burst behavior of most printers. Many 
printers have on-board RAM buffers which typically hold a 
line or a fixed amount of characters. These buffers fill up 
without the printer going busy, or going busy for a very 
short period (less than 10 instructions) between characters. 
A line of characters can be very quickly output to the 
printer, then the printer is busy for a long time while the 
characters are being printed. This new device call allows 
background spooling programs to use this burst behavior 
efficiently. Rather than take the overhead of a device 
driver call for each character, or risk getting stuck in the 
device driver outputting a block of characters, this call 
allows a burst of characters to be output without the device 
driver having to wait for the device to be ready. 
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THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS: 

Under certain circumstances, the BIOS may be asked _ to 
perform a write operation of 64K bytes, which seems to be a 
"wrap around" of the transfer address in the BIOS I/0 
packet. This request arises due to an optimization added to 
the write code in MS-DOS. It will only manifest on _ user 
writes that are within a sector size of 64K bytes on files 
"growing" past the current EOF. It is allowable for’ the 
if it so chooses. For example, a write of 10000H bytes 
worth of sectors with a transfer address of XXX:1 could 
ignore the last two bytes. A user program can never request 
an I/O of more than FFFFH bytes and cannot wrap around (even 
to 0) in the transfer segment. Therefore, in this case, the 
last two bytes can be ignored. 


MS-DOS maintains two FATS. If the DOS has problems’ reading 


the first, it automatically tries the second before 
reporting the error. The BIOS is responsible for all 
retries. 


Although the COMMAND.COM handler does no automatic. retries, 
there are applications that have their own Interrupt 24H 
handlers that do automatic retries on certain types of 
Interrupt 24H errors before reporting them. 


2.7.5 NON DESTRUCTIVE READ NO WAIT 


Command code = 5 


NON DESTRUCTIVE READ NO WAIT - ES:BX ~-> 


| 13-BYTE Request header 
BYTE read from device 


This call allows MS-DOS to look ahead one input character. 
The device sets the done bit in the status word. 


If the character device returns busy bit = 0 (there are 
characters in the buffer), then the next character that 
would be read is returned. This character is not removed 
from the input buffer (hence the term "Non Destructive 
Read"). If the character device returns busy bit = 1, there 
are no characters in the buffer. 
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2.7.6 OPEN or CLOSE 


Command codes = 13 and 14 


OPEN or CLOSE - ES:BX -> 


13-BYTE Static request header 


These functions are only called by MS-DOS 3.x if the device 
driver sets the OPEN/CLOSE/RM attribute bit in the device 
header. They are designed to inform the device about 
current file activity on the device. On block devices, they 
can be used to manage local buffering. The device can keep 
a reference count. Every OPEN causes the device to 
increment the count, every CLOSE to decrement. When the 
count goes to zero; it means there are no open files on the 
device, and the device should flush any buffers that have 
been written to that may have been used inside the device 
because it is now "legal" for the user to change the media 
On a removable media drive. 


There are problems with this mechanism on block devices 
because programs that use FCB calls can open files without 
closing them. It is therefore advisable to reset the count 
to zero without flushing the buffers when the answer to "has 
the media been changed?" is yes and the BUILD BPB call is 
made to the device. 


These calls are of more use on character devices. The OPEN 
call can be used to send a device initialization string. On 
a printer, this could cause a string for setting font’ and 
page size characteristics to be sent to the printer so that 
it would always be in a known State at the start of an I/O 
stream. Using IOCTL to set these pre- and post-strings 
provides a flexible mechanism of Serial I/O device stream 
control. The reference count mechanism can also be used to 
detect a Simultaneous access error. It may be desirable to 
disallow more than one OPEN on a device at any given time. 
In this case, a second OPEN would result in an error. 


Note that since all processes have access to stdin, stdout, 
stderr, stdaux, and stdprn (handles 0,1,2,3,4), the CON, 
AUX, and PRN devices are always open. 
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2.7.7 REMOVABLE MEDIA 


Command code = 15 


REMOVABLE MEDIA - ES:BX -> 


13-BYTE Static request header 


This function is only called by MS-DOS 3.x if the device 
driver sets the OPEN/CLOSE/RM attribute bit in the device 
header. This call is given only to block devices by a 
subfunction of the IOCTL system call. It is sometimes 
desirable for a utility to know whether it is dealing with a 
non-removable media drive (Such as a hard disk), or a 
removable media drive (like a floppy). An example is’ the 
FORMAT utility which prints different versions of some of 
the prompts. 


The information is returned in the busy bit of the status 


word. Lf the busy bit is 1, then the media is 
non-removable. If the busy bit is 0, then the media is 
removable. Note that no checking of the error bit is 


performed. It is assumed that this call always succeeds. 


2.7.8 STATUS 


Command codes = 6 and 10 


STATUS Calls ES:BX -> 


13-BYTE request header 


This call returns information to the DOS as to whether data 
is waiting for input or output. All the driver must do is 
set the status word and the busy bit as follows: 


For output on character devices: If the driver 
sets bit 9 to 1 on return, it informs the DOS that 
a write request (if made) would wait for completion 
of a current request. Tf it is 0, there is no 
current request and a write request (if made) would 
Start immediately. 


For input on character devices with a buffer: A 
return of 1 implies that no characters are buffered 
and that a read request (if made) would go to the 
physical device. If it is 0 on return, then there 
are characters in the device buffer and ae read 


would not be blocked. A return of O implies that 
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the user has typed something. MS-DOS assumes”~ that 
all character devices have an input type-ahead 
buffer. Devices that do not have aéetype-ahead 
buffer should always return busy = 0 so that the 
DOS will not hang waiting for something to get into 
a non-existent buffer. 


2.7.9 FLUSH 


Command codes = 7 and ll 


FLUSH Calls - ES:BX -> 


13-BYTE request header 


The FLUSH call tells the driver to flush (terminate) all 


pending requests. This call is used to flush the input 
queue on character devices. 


The device driver performs the flush function, sets’ the 
status word, and returns. 


2.8 MEDIA DESCRIPTOR BYTE 


In MS-DOS, the media descriptor byte is used to inform’ the 
DOS that a different type of media is present. The media 
descriptor byte can be any value between 0 and FFH. It does 
not have to be the same as the FAT ID byte. The FAT ID 
byte, which is the first byte of the FAT, was used in MS-DOS 
1.00 to distinguish between different types of disk media 
and may be used as well under 2.x and 3.x disk device 
drivers. However, FAT ID bytes only have significance for 
block device drivers where the NON FAT ID bit is not~ set 
(0). 


Values of the media descriptor byte or the FAT ID byte have 
no significance to MS-DOS. They are passed to the device 
driver to facilitate media determination in any way the OEM 
chooses to implement. 
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Important 


When the BPB call is made, if the media byte returned 
in the new BPB is the same as the old media byte, the 
DOS does not rebuild its internal structure for the 


device. MS-DOS will treat the disk as though the 
format has not changed, even though the physical disk 
might have changed. Therefore, each BPB must have a 
unique media descriptor byte. 


2.9 FORMAT OF A MEDIA DESCRIPTOR TABLE 


The MS-DOS file system uses a linked list of pointers (one 
for each cluster or allocation unit) called the File 
Allocation Table (FAT). Unused clusters are represented by 
zero and end of file by FFF (or FFFF on units with 16-bit 
FAT entries). No valid entry should ever point to a zero 
entry, but if it does, the first FAT entry (which would be 
pointed to by a zero entry) was reserved and set to end of 
chain. Eventually, several end of chain values were defined 
({F]FF8-[(F]FFF), and these were used to distinguish 
different types of media. 


A preferrable technique is to write a complete media 
descriptor table in the boot sector and use it for media 
identification. To ensure backward compatibility for 
systems whose drivers do not set the NON FAT ID bit 
(including the IBM PC implementation), it is necessary also 
to write the FAT ID bytes during the FORMAT process. 


To allow more flexibility for supporting many different disk 
formats in the future, it is recommended that the 
information relating to the BPB for a particular piece of 
media be kept in the boot sector. Figure 2.3 shows the 
format of such a boot sector. 
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3 BYTE Near JUMP to boot code 

8 BYTES OEM name and version 
WORD Bytes per sector 

BYTE Sectors per allocation unit 


WORD Reserved sectors 


@— Wvw 


BYTE Number of FATS 
WORD Number of root dir entries 


WORD Number of sectors in logical 
image 


BYTE Media descriptor 


Wy —> 


WORD Number of FAT sectors 
WORD Sectors per track 


WORD Number of heads 


WORD Number of hidden sectors 


Figure 2.3. Format of Boot Sector 


The three words at the end ("Sectors per track," "Number of 


heads," and "Number of hidden sectors") are not used by the 
DOS but may be used by device drivers. They are intended to 
help the device driver understand the media. "Sectors per 


track" and “Number of heads" are useful for supporting 
different media which may have the same logical layout but a 
different physical layout (e.g., 40 track, double-sided 
versus 80 track, Single-sided). "Sectors per track" tells 
the device driver how the logical disk format is laid out on 
the physical disk. "Number of hidden sectors" may be used 
to support drive-partitioning schemes. 


The following procedure is recommended for media 
determination by NON FAT ID format drivers: 


1. Read the boot sector of the drive into the 1l-sector 
scratch space pointed to by the DWORD Transfer 
address. 


2. Determine if the first byte of the boot sector is 
an E9H or EBIT (the first byte of a 3-byte NEAR or 
2-byte short jump) or an EBH (the first byte of a 
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2-byte jump followed by a NOP). If so, a BPB is 
located beginning at offset 3. Return a pointer to 
it. 


3. If the boot sector does not have a BPB table, it 
probably is a disk formatted under a version 1.x 
implementation of MS-DOS and probably uses a FAT ID 
byte for media determination. 


The driver may optionally attempt to read the first 
sector of the FAT into the l-sector scratch area 
and read the first byte to determine media type 
based upon whatever FAT ID bytes may have been used 
on disks that are expected to be read by this 
system. Return a pointer to a hard-coded BPB. 


2.10 THE CLOCK DEVICE 


MS-DOS assumes that some sort of clock is available in the 
system. This may either be a CMOS real-time clock or an 
interval timer which is initialized at boot time by the 
user. The CLOCK device defines and performs functions like 
any other character device except that it is identified by a 
bit in the attribute word. The DOS uses’ this bit to 
identify it and consequently this device may take any name. 
The IBM implementation uses "S$CLOCK" so as not to conflict 
with existing files named "CLOCK." 


The CLOCK device is unique in that MS-DOS will read or write 
a 6-byte sequence which encodes the date and time. A write 
to this device will set the date and time, and a read will 
get the date and time. 


Figure 2.4 illustrates the binary time format used by the 
CLOCK device: 


byte 0 byte 1 byte 2 byte 3 byte 4 byte 5 


Figure 2.4 CLOCK Device Format 


Fa 


, 
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2.11 ANATOMY OF A DEVICE CALL 


The following steps illustrate what happens when MS-DOS 
calls on a block device driver to perform a WRITE request: 


ds 


MS-DOS writes a request packet in a reserved area 
of memory. 


MS-DOS calls the block device driver strategy entry 
point. 


The device driver saves the ES and BX registers 


(ES:BX points to the request packet) and does a FAR 
return. 


MS-DOS calls the interrupt entry point. 


The device driver retrieves the pointer to. the 
request packet and reads the command code (offset 
2) to determine that this is a write request. The 
device driver converts the command code to an index 
into a dispatch table and control passes to. the 
disk write routine. 


The device driver reads the unit code (offset 1) to 
determine to which disk drive it is supposed to 
write. 


Since the command iS a disk write, the device 
driver must get the transfer address (offset 14), 
the sector count (offset 18), and the start sector 
(offset 20) in the request packet. 


The device driver translates the first logical 
sector number into ae track, head, and sector 
number. 


The device driver writes the specified number of 
sectors, starting at the beginning sector on the 
drive defined by the unit code (the subunit defined 
by this device driver), and transfers data from the 
transfer address indicated in the request packet. 
Note that this may involve multiple write commands 
to the disk controller. 
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10. After the transfer is complete, the device driver 
must report the status of the request to MS-DOS by 
setting the done bit in the status word (offset 3 
in the request packet). It reports the number of 
sectors actually transferred in the sector count 
area of the request packet. 


11. If an error occurs, the driver sets the done bit 
and the error bit in the status word and fills in 
the error code in the lower half of the status 
word. The number of sectors actually transferred 
must be written in the request header. It is not 
sufficient just to set the error bit of the status 
word. 


12. The device driver does a FAR return to MS-DOS. 


The device drivers should preserve the state of MS-DOS. 
This means that all registers (including flags) should be 
preserved. The direction flag and interrupt enable bits are 
critical. When the interrupt entry point in the device 
driver is called, MS-DOS has room for about 40 to 50 £4bytes 
on its internal stack. Your device driver should switch to 
a local stack if it uses extensive stack operations. 
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2.12 EXAMPLE OF DEVICE DRIVERS 


The following examples illustrate a block device driver and 
a character device driver program. 


2.12.1 Block Device Driver 


gRKKEKKAKKEKKEEKREKEKKEEKE KR BLOCK DEVICE *#RRRRKKKEEK EKER KE KK 
TITLE 5 1/4" DISK DRIVER FOR SCP DISK-MASTER 
;This driver is intended to drive up to four 5 1/4" drives 


;hooked to the Seattle Computer Products DISK MASTER disk 
;controller. All standard IBM PC formats are supported. 


FALSE EQU 0 

TRUE EQU NOT FALSE 
:The I/O port address of the DISK MASTER 
DISK EQU QOEOH 
:DISK+0 

; 1793 Command/Status 
;DISK+1 

; 1793 Track 
:;DISK+2 

: 1793 Sector 
*>DISK+3 

; 1793 Data 
;DISK+4 

: Aux Command/Status 
*DISK+5 

; Wait Sync 

*Back side select bit 
BACKBIT EQU 04H 

25 1/4" select bit 

SMALBIT EQU 10H 
;Double Density bit 

DDBIT EQU 08H 


;Done bit in status register 
DONEBIT EQU 01H 


;Use table below to select head step speed. 
7Step times for 5" drives 
sare double that shown in the table. 


Step value 1771 1793 


=e =e 6 6"O8 


0 6ms 3ms 
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: 1 6ms 6ms 
: 2 10ms 10ms 
: 3 20ms 15ms 
STPSPD EQU 1 

NUMERR EQU ERROUT-ERRIN 
CR EQU ODH 

LF EQU OAH 


CODE SEGMENT 
ASSUME CS:CODE,DS:NOTHING,ES:NOTHING,SS:NOTHING 


DEVICE HEADER 


RVDEV LABEL WORD 


DW -l1,-1 
DW 0000 IBM format-compatible, Block 
DW STRATEGY 
DW DRVSIN 
DRVMAX DB 4 
DRVTBL LABEL WORD 
DW DRVSINIT 
DW MEDIASCHK 
DW GETSBPB 
DW CMDERR 
DW DRVS$ READ 
DW EXIT 
DW EXIT 
DW EXIT 
DW DRVSWRIT 
DW DRVSWRIT 
DW EXIT 
DW EXIT 
DW EXIT 
pee ee ee ee ee eo 
v 
: STRATEGY 
PTRSAV DD 0 
STRATP PROC FAR 
STRATEGY: 
MOV WORD PTR [PTRSAV] ,BX 
MOV WORD PTR [PTRSAV+2] ,ES 
RET 


a oem Ce om Cute euie GoD eEmD Seed Cue Gem sep Geen GED Sulp coy SD Ce COD me iD MD SUE) mm Gn) cD OD me OE CED CED Guln Se) GUD CD ee GU a 
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CMDLEN = 0 *LENGTH OF THIS COMMAND 
UNIT = 1 ;SUB UNIT SPECIFIER 
CMDC = 2 _;}COMMAND CODE 
STATUS = 3 >STATUS 
MEDIA = 13 *sMEDIA DESCRIPTOR 
TRANS = 14 *TRANSFER ADDRESS 
COUNT = 18 *COUNT OF BLOCKS OR CHARACTERS 
START = 20 sFIRST BLOCK TO TRANSFER 
DRVSIN: 
PUSH SI 
PUSH AX 
PUSH CX 
PUSH DX 
PUSH DI 
PUSH BP 
PUSH DS 
PUSH ES 
PUSH BX 
LDS BX, [PTRSAV] *>GET POINTER TO I/O PACKET 
MOV AL,BYTE PTR [BX] .UNIT >AL = UNIT CODE 
MOV AH,BYTE PTR [BX] .MEDIA ;AH = MEDIA DESCRIP 
MOV CX,WORD PTR [BX].COUNT ;CX = COUNT 
MOV DX,WORD PTR [BX].START >DX = START SECTOR 
PUSH AX 
MOV AL,BYTE PTR [BX].CMDC >Command code 
CMP AL,15 
JA CMDERRP Bad command 
CBW 
SHL AX,1 7:2 times command = 
word table index 
MOV SI,OFFSET DRVTBL 
ADD SI,AX :;Index into table 
POP AX Get back media 
sand unit 
LES DI,DWORD PTR [BX].TRANS ;ES:DI = TRANSFER 
s ADDRESS 
PUSH CS 
POP DS 
ASSUME DS:CODE 
JMP WORD PTR [STI] >GO DO COMMAND 


EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 


SSUME DS:NOTHING 
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AX Clean stack 

AL,3 sUNKNOWN COMMAND ERROR 
SHORT ERRSEXIT 2 

BX, [PTRSAV] 


WORD PTR [BX].COUNT,CX ;# OF SUCCESS. I/Os 


AH, 10000001B ;MARK ERROR RETURN 
SHORT ERRI1 


FAR 
AH,00000001B 
BX, [PTRSAV] 


WORD PTR [BX] .STATUS ,AX 
;MARK OPERATION COMPLETE 


;RESTORE REGS AND RETURN 


-1,-l1,-1,-1l 
0 


8 sNumber of sectors on device 
13 *>MAXIMUM SECTOR 
15 *>MAXIMUM HEAD 


preserve order of drive and curhd! 


;PHYSICAL DRIVE CODE 
;CURRENT HEAD 
;CURRENT SECTOR 
;CURRENT TRACK 


oooo 


CMDERRP: 
POP 
CMDERR: 
MOV 
JMP 
ERRSCNT: LDS 
SUB 
ERRSEXIT: 
7AL has error code 
MOV 
JMP 
EXITP PROC 
EXIT: MOV 
ERR1: LDS 
MOV 
POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 
RET 
EXITP ENDP 
CURDRV DB 
TRKTAB DB 
SECCNT DW 
DRVLIM = 
SECLIM = 
HDLIM = 
sWARNING - 
DRIVE DB 
CURHD DB 
CURSEC DB 
CURTRK DW 
; 
MEDIASCHK: 


ASSUME DS:CODE 


TEST 


;Always indicates Don't know 


AH ,00000100B ;TEST IF MEDIA REMOVABLE 
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JZ MEDIASEXT 
XOR DI,DI ;SAY I DON'T KNOW 
MEDIASEXT: 
LDS BX, [PTRSAV] 
MOV WORD PTR [BX].TRANS,DI 
JMP EXIT 
BUILDSBPB: 
ASSUME DS:CODE 
MOV AH,BYTE PTR ES: [DI] ;GET FAT ID BYTE 
CALL BUILDBP ; TRANSLATE 
SETBPB: LDS BX, [PTRSAV] 
MOV [BX] .MEDIA,AH 
MOV [BX] .COUNT,DI 
MOV [BX] .COUNT+2,CS 
JMP EXIT 
BUILDBP: 


ASSUME DS:NOTHING 
;AH is media byte on entry 
;DI points to correct BPB on return 


PUSH AX 
PUSH CX 
PUSH DX 
PUSH BX 
MOV CL,AH *SAVE MEDIA 
AND CL,0F8H s NORMALIZE 
CMP CL,0OF8H :COMPARE WITH GOOD MEDIA BYTE 
JZ GOODID 
MOV AH , OFEH ;DEFAULT TO 8-SECTOR, 
sSINGLE-SIDED 
GOODID: 
MOV AL,1 :SET NUMBER OF FAT SECTORS 
MOV BX ,64*256+8 ;SET DIR ENTRIES AND SECTOR MAX 
MOV CX,40*8 sSET SIZE OF DRIVE 
MOV DX,01*256+1 ;SET HEAD LIMIT & SEC/ALL UNIT 
MOV DI,OFFSET DRVBPB 
TEST AH,00000010B ;TEST FOR 8 OR 9 SECTOR 
JNZ HAS8 *>NZ = HAS 8 SECTORS 
INC AL s;INC NUMBER OF FAT SECTORS 
INC BL ;INC SECTOR MAX 
ADD Cx, 40 s INCREASE SIZE 
HAS8: TEST AH,00000001B TEST FOR 1 OR 2 HEADS 
JZ HAS1L 7Z = 1 HEAD 
ADD CX ,CX ;DOUBLE SIZE OF DISK 
MOV BH,112 es INCREASE # OF DIREC. ENTRIES 
INC DH ;INC SEC/ALL UNIT 
INC DL ;INC HEAD LIMIT 
HAS1: MOV BYTE PTR [DI].2,DH 
MOV BYTE PTR [DI].6,BH 
MOV WORD PTR [DI].8,CX 
MOV BYTE PTR [DI].10,AH 
MOV BYTE PTR [DI].11,AL 
MOV BYTE PTR [DI].13,BL 
MOV BYTE PTR [DI].15,DL 


MS-DOS 


DEVICE DRIVERS 


POP BX 
POP DX 
POP CX 
POP AX 
RET 


DISK I/O HANDLERS 
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; 
; 
; 
; 
sENTRY: 
; AL = DRIVE NUMBER (0-3) 
: AH = MEDIA DESCRIPTOR 
: CX = SECTOR COUNT 
: DX = FIRST SECTOR 
7 DS = CS 
: ES:DI = TRANSFER ADDRESS 
csEXIT: 
: IF SUCCESSFUL CARRY FLAG = 0 
: ELSE CF=1 AND AL CONTAINS (MS-DOS) ERROR CODE, 
CX # sectors NOT transferred 
DRVSREAD: 
ASSUME DS:CODE 
JCXZ DSKOK 
“CALL SETUP 
JC DSKSIO 
CALL DISKRD 
JMP SHORT DSKSIO 
DRVSWRIT: 
ASSUME DS:CODE 
JCXZ DSKOK 
CALL SETUP 
JC DSKSIO 
CALL DISKWRT 
ASSUME DS:NOTHING 
DSKSIO: JNC DSKOK 
JMP ERRSCNT 
DSKOK: JMP EXIT 
SETUP: 
ASSUME DS:CODE 
;Input same as above 


7;On output 


ES:DI 


else 


=e =O OO ~O WO WE WE WE 


= Trans addr 


DS:BX Points to BPB 
Carry set if error (AL is error code (MS-DOS) ) 


[DRIVE] = Drive number (0-3) 


{[SECCNT] = Sectors to transfer 
[CURSEC] = Sector number of start of I/0 
[CURHD] = Head number of start of I/0 


Set 
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INRANGE: 


SEEK: 


: [CURTRK] = Track # of start of I/O ;Seek performed 
; All other registers destroyed 


XCHG 
CALL 
MOV 
ADD 
CMP 


JBE 
MOV 
STC 
RET 


MOV 
MOV 
XCHG 


BX,DI 7ES:BX = TRANSFER ADDRESS 
BUILDBP ;DS:DI = PTR TO B.P.B 
SI,CX 

SI,DX 


SI,WORD PTR [DI].DRVLIM 

;COMPARE AGAINST DRIVE MAX 
INRANGE 
AL,8 


[DRIVE] ,AL 


[SECCNT] ,CX ;SAVE SECTOR COUNT 

AX,DX ;SET UP LOGICAL SECTOR 
7;FOR DIVIDE 

DX ,DX 


WORD PTR [DI] .SECLIM ;DIVIDE BY SEC PER TRACK 
DL 

[CURSEC] ,DL ;SAVE CURRENT SECTOR 
CX,WORD PTR [DI].HDLIM ;GET NUMBER OF HEADS 
DX ,DX ;DIVIDE TRACKS BY HEADS PER CYLINDER 
CX 


[CURHD] ,DL ;SAVE CURRENT HEAD 

[CURTRK] , AX *SAVE CURRENT TRACK 

BX :Xaddr 

DI ;BPB pointer 

CHKNEW sUnload head if change drives 
DRIVESEL 

BL, [DRIVE] 

BH, BH *BX drive index 

BX,OFFSET TRKTAB sGet current track 
AX, [CURTRK] 

DL,AL *Save desired track 

AL,DS: [BX] *sMake desired track current 
DISK+1,AL *Tell Controller current track 
AL,DL sAt correct track? 

SEEKRET :Done if yes 

BH,2 ;Seek retry count 

AL,-1 Position Known? 

NOHOME If not home head 

HOME 

SEEKERR 

AL, DL 

DISK+3 ,AL *Desired track 

AL, L1CH+STPSPD 7Seek 

DCOM 

AL ,98H ;Accept not rdy, seek, & CRC errors 


SEEKRET 
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JS SEEKERR 
DEC BH 
JNZ TRYSK 
SEEKERR: 
MOV BL, [DRIVE] 
XOR BH,BH 
ADD BX,OFFSET TRKTAB 
MOV BYTE PTR DS: [BX] 
CALL GETERRCD 
MOV CX, [SECCNT] 
POP BX 
POP DI 
RET 
SEEKRET: 
POP BX 
POP DI 
CLC 
RET 
ge a ee 
: READ 
; 
DISKRD: 
ASSUME DS:CODE 
MOV CX, [SECCNT] 
RDLP: 
CALL PRESET 
PUSH BX 
MOV BL,10 
MOV DX ,DISK+3 
RDAGN : 
MOV AL, 80H 
CLI 
OUT DISK,AL 
MOV BP,DI 
JMP SHORT RLOOPENTRY 
RLOOP : 
STOSB 
RLOOPENTRY : | 
IN AL,DISK+5 
SHR AL,1 
IN AL ,DX 
JNC RLOOP 
STI 
CALL GETSTAT 
AND AL, 9CH 
JZ RDPOP 
MOV DI,BP 
DEC BL 
JNZ RDAGN 
CMP AL, 10H 
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s>No retries if not ready 


>BX drive index 
Get current track 
sMake current track 
: unknown 


pri 


sNothing transferred 
*BPB pointer 
:Xaddr 


;BPB pointer 
*Xaddr 


;Retry count 
;Data port 


»sRead command 
Disable for 1793 


;Output read command 
;Save address for retry 


sWait for DRQ or INTRQ 
:;Read data 


sInts OK now 


sOk 
*Get back transfer 


sRecord not found? 
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JNZ GOT CODE 
MOV Ali L 
GOT CODE: 
tt CALL GETERRCD 
POP BX 
RET 
RDPOP: 
POP BX 
LOOP RDLP 
CLC 
RET 
; 
; WRITE 
; 
DISKWRT: 
ASSUME DS:CODE 
MOV CX, [SECCNT] 
MOV SI,DI 
PUSH ES 
POP DS 
ASSUME DS:NOTHING 
WRLP: 
CALL PRESET 
PUSH BX 
MOV BL, 10 
MOV DX ,DISK+3 
WRAGN : 
MOV AL, OAOH 
CLI 
OouT DISK,AL 
MOV BP,SI 
WRLOOP : 
IN AL,DISK+5 
SHR AL,1l 
LODSB 
OUT DX ,AL 
JNC WRLOOP 
STI | 
DEC SI 
CALL GETSTAT 
AND AL, OFCH 
JZ WRPOP 
MOV SI,BP 
DEC BL 
JINZ WRAGN 
CALL GETERRCD 
POP BX 
RET 


WRPOP: 
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;Retry count 
;Data port 


;Write command 

:Disable for 1793 
;Output write command 
;Save address for retry 


Get data 
eWrite data 


s;Ints OK now 


2Ok 
Get back transfer 
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POP BX 
LOOP WRLP 
CLC 
RET 
PRESET: 
ASSUME DS:NOTHING 
MOV AL, [CURSEC] 
CMP AL,CS: [BX] .SECLIM 
JBE GOTSEC 
MOV DH, [CURHD] 
INC DH 
CMP DH,CS: [BX] _HDLIM 
JB SETHEAD sSelect new head 
CALL STEP *Go on to next track 
XOR DH , DH :Select head zero 
SETHEAD: 
MOV [CURHD] ,DH 
CALL DRIVESEL 
MOV AL,Ll :First sector 
MOV [CURSEC] ,AL 7Reset CURSEC 
GOTSEC: 
OUT DISK+2,AL ;Tell controller which sector 
INC [CURSEC] ;We go on to next sector 
RET 
STEP: 
ASSUME DS:NOTHING 
MOV AL,58H+STPSPD ;Step in w/ update, no verify 
CALL DCOM 
PUSH BX 
MOV BL, [DRIVE] 
XOR BH,BH >BX drive index 
ADD BX,OFFSET TRKTAB :Get current track 
INC BYTE PTR CS: [BX] sNext track 
POP BX 
RET 
HOME : 
ASSUME DS:NOTHING 
MOV BL, 3 
TRYHOM: 
MOV AL, OCH+STPSPD ;Restore with verify 
CALL DCOM 
AND AL,98H 
JZ RET3 
JS HOMERR ;No retries if not ready 
PUSH AX ;Save real error code 
MOV AL,58H+STPSPD ;Step in w/ update no verify 
CALL DCOM 
DEC BL 
POP AX 7;Get back real error code 
JNZ TRYHOM 


HOMERR: 
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STC 

RET3: RET 

CHKNEW: 

ASSUME DS:NOTHING 
MOV AL, [DRIVE] Get disk drive number 
MOV AH ,AL 
XCHG AL, [CURDRV] sMake new drive current. 
CMP AL,AH ;Changing drives? 
JZ RETL sNo 


If changing drives, unload head so the head load delay 
one-shot will fire again. Do it by seeking to the same 
track with the H bit reset. 


me ~O TO TO 


IN AL,DISK+1 sGet current track number 
OUT DISK+3,AL *sMake it the track to seek 
MOV AL, 10H 7Seek and unload head 
DCOM: 
ASSUME DS:NOTHING 
OUT DISK,AL 
PUSH AX 
AAM ;Delay 10 microseconds 
POP AX 
GETSTAT: 
IN AL,DISK+4 
TEST AL, DONEBIT 
JZ GETSTAT 
IN AL,DISK 


RET1: RET 


DRIVESEL: 

ASSUME DS:NOTHING 

Select the drive based on current info 
;Only AL altered 


MOV AL, [DRIVE] 
OR AL,SMALBIT + DDBIT 75 1/4" IBM PC disks 
CMP [CURHD] ,0 
JZ GOTHEAD 
OR AL,BACKBIT Select side 1 
GOTHEAD: 
OUT DISK+4,AL *Select drive and side 
RET 
GETERRCD: 
ASSUME DS:NOTHING 
PUSH CX 
PUSH ES 
PUSH DI 
PUSH CS 
POP ES ;Make ES the local segment 
MOV CS: [LSTERR] ,AL ;Terminate list w/ error code 
MOV CX ,NUMERR sNumber of error conditions 


MOV DI,OFFSET ERRIN ;Point to error conditions 
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REPNE SCASB 


MOV AL,NUMERR-1[DI] ;Get translation 

STC ;Flag error condition 

POP DI 

POP ES 

POP CX 

RET zand return 
KEK KKREKKEKKEEKKEERKRKEKRKER KER EKRER EEE RRR KERKEKEKRERERREKREREEEKERKER 
; BPB FOR AN IBM FLOPPY DISK, VARIOUS PARAMETERS ARE 
: PATCHED BY BUILDBP TO REFLECT THE TYPE OF MEDIA 
: INSERTED 
: This is a nine sector single side BPB 
DRVBPB: 

DW 512 ;Physical sector size in bytes 

DB 1 :Sectors/allocation unit 

DW 1 ;Reserved sectors for DOS 

DB 2 ># Of allocation tables 

DW 64 ;Number directory entries 

DW 9*40 ;Number 512-byte sectors 

DB 11111100B sMedia descriptor 

DW 2 sNumber of FAT sectors 

DW 9 sSector limit 

DW ai sHead limit 
INITAB DW DRVBPB ;Up to four units 

DW DRVBPB 

DW DRVBPB 

DW DRVBPB 
ERRIN: ;DISK ERRORS RETURNED FROM THE 1793 CONTROLER 

DB 80H >NO RESPONSE 

DB 40H ;Write protect 

DB 20H sWrite Fault 

DB 10H *>SEEK error 

DB 8 CRC error 

DB 1 ;Mapped from 10H 

; (record not found) on READ 

LSTERR DB 0 sALL OTHER ERRORS 
ERROUT: ;RETURNED ERROR CODES CORRESPONDING TO ABOVE 

DB 2 *NO RESPONSE 

DB 0 sWRITE ATTEMPT 

;ON WRITE-PROTECT DISK 

DB OAH ;WRITE FAULT 

DB 6 :SEEK FAILURE 

DB 4 BAD CRC 

DB 8 :SECTOR NOT FOUND 

DB 12 :GENERAL ERROR 
DRVSINIT: 


e 
’ 


; Determine number of physical drives by reading CONFIG.SYS 
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; 
ASSUME 
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DS : CODE 
PUSH DS 
LDS SI, [PTRSAV] 
ASSUME DS:NOTHING 
LDS SI,DWORD PTR [SI.COUNT] ;DS:SI points to 
;CONFIG.SYS 
SCAN LOOP: 
~ CALL SCAN_SWITCH 
MOV AL,CL 
OR AL,AL 
JZ SCAN4 
CMP AL,"s" 
JZ SCAN4 
WERROR: POP DS 
ASSUME DS:CODE 
MOV DX,OFFSET ERRMSG2 
WERROR2: MOV AH ,9 
INT 21H 
XOR AX, AX 
PUSH AX -No units 
JMP SHORT ABORT 
BADNDRV: 
POP DS 
MOV DX,OFFSET ERRMSG1 
JMP WERROR2 
SCAN4: 
ASSUME DS:NOTHING 
;BX is number of floppies 
OR BX,BX 
JZ BADNDRV sUSer error 
CMP BX,4 
JA BADNDRV sUser error 
POP DS 
ASSUME DS:CODE 
PUSH BX Save unit count 
ABORT: LDS BX, [PTRSAV] 
ASSUME DS:NOTHING 
POP AX 
MOV BYTE PTR [BX] .MEDIA,AL sUnit count 
MOV [DRVMAX] , AL 
MOV WORD PTR [BX].TRANS,OFFSET DRVSINIT ;SET 
;BREAK ADDRESS 
MOV [BX] . TRANS+2,CS 
MOV WORD PTR [BX].COUNT,OFFSET INITAB 
;SET POINTER TO BPB ARRAY 
MOV [BX] .COUNT+2,CS 
JMP EXIT 
a 
; PUT SWITCH IN CL, VALUE IN BX 
tf 
SCAN SWITCH: 
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XOR BX ,BX 
MOV CX ,BX 
LODSB 
CMP AL, 10 
JZ NUMRET 
CMP AL,"-" 
TZ GOT SWITCH 
CMP AL,"/" 
INZ SCAN SWITCH 
GOT SWITCH: | 
CMP BYTE PTR [SI+1],":" 
JNZ TERROR 
LODSB 
OR AL, 20H : CONVERT TO LOWERCASE 
MOV CL,AL ; GET SWITCH 
LODSB s SKIP ":" 
a 
. GET NUMBER POINTED TO BY [STI] 
; WIPES OUT AX,DX ONLY BX RETURNS NUMBER 
a 
GETNUM1L:LODSB 
SUB AL,"0" 
JB CHKRET 
CMP AL,9 
JA CHKRET 
CBW 
XCHG AX,BX 
MOV DxX,10 
MUL DX 
ADD BX,AX 
JMP GETNUM1 
CHKRET: ADD AL,"0" 
CMP AL 
JBE NUMRET 
CMP AL,"-" 
JZ NUMRET 
CMP AL,"/" 
JZ NUMRET 
TERROR: 
POP DS : GET RID OF RETURN ADDRESS 
JMP WERROR 
NUMRET: DEC SI 
RET 
ERRMSG1 DB "SMLDRV: Bad number of drives",13,10,"$" 
ERRMSG2 DB "SMLDRV: Invalid parameter",13,10,"$" 


CODE ENDS 


Pada 
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2.12.2 Character Device Driver 


The following program illustrates a character device driver 
program. 


kkk kkk kkk kkk ke RKEK A CHARACTER DEVICE #8 RKKKKKKEKEKKEKR KK 


TITLE VT52 CONSOLE FOR 2.0 (IBM) 


ee 
ee 
ee 
e 
ee 
ee 
e 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
e 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
ee 
e 
ee 
ee 
ee 


IBM ADDRESSES FOR I/O 


a i i i ed 


Se ee tele ie ce tet ee ieee wee ee eee bs Se locate. ‘elo: eo) 8. ee ee (Seb ele Sle. s.eie Saale ise e eleltes 
oeeoee#eee8@ e@eeee?ee#egee#ek#kerteet ee e eoeeese eoeoe7e#eer#Fe#ee#e#eeesteee eet eeeteeoee#e#e#eernree7x#+0#»#eteeeee@# 


CR=13 >CARRIAGE RETURN 

BACKSP=8 > BACKSPACE 

ESC=1BH 

BRKADR=6CH >006C BREAK VECTOR ADDRESS 

ASNMAX=200 ;SIZE OF KEY ASSIGNMENT BUFFER 
CODE SEGMENT BYTE 


ASSUME CS:CODE,DS:NOTHING,ES:NOTHING 


C ON - CONSOLE DEVICE DRIVER 


e 
s 
e 
‘ 
e 
f 
e 
f 
Cc 


ONDEV: ;HEADER FOR DEVICE "CON" 
DW =L,-1 
DW 1000000000010011B ;CON IN AND CON OUT 
DW STRATEGY 
DW ENTRY 
DB "CON 

; COMMAND JUMP TABLES 

CONTBL: 
DW CONS INIT 
DW EXIT 
DW EXIT 
DW CMDERR 
DW CONS READ 
DW CON$RDND 
DW EXIT 
DW CONSFLSH 
DW CONSWRIT 
DW CONSWRIT 
DW EXIT 
DW EXIT 


CMDTABL DB ‘A' 
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PTRSAV 


STRATP 


DD 


PROC 


STRATEGY : 


STRATP 


ENTRY : 


MOV 


ENDP 


PUSH 
PUSH 
PUSH 
PUSH 


CUU ;Cursor up 
'B! 
CUD scursor down 
‘ci 
CUF ;cursor forward 
'p!t 
CUB ;Cursor back 
'H! 
CUH ;cursor position 
'j! 
ED ;erase display 
'K! 
EL ;erase line 
ty! 
CUP ;Cursor position 
t= 8 
J 
PSCP ;Save cursor position 
tk? 
PRCP ;restore cursor position 
' ' 
y 
RM sreset mode 
"yx! 
SM 7set mode 
00 


0 ;LENGTH OF THIS COMMAND 

1 ;SUB UNIT SPECIFIER 

2 ; COMMAND CODE 

3 ;STATUS 

13 ;MEDIA DESCRIPTOR 

14 ; TRANSFER ADDRESS 

18 ;COUNT OF BLOCKS OR CHARACTERS 
20 ;FIRST BLOCK TO TRANSFER 

0 

FAR 


WORD PTR CS: [PTRSAV] ,BX 
WORD PTR CS: [PTRSAV+2] ,ES 
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PUSH DI 

PUSH BP 

PUSH DS 

PUSH ES 

PUSH BX 

LDS BX,CS:[PTRSAV] ;GET POINTER TO I/O PACKET 
MOV CX,WORD PTR DS: [BX] .COUNT :CX = COUNT 
MOV AL,BYTE PTR DS: [BX].CMD 

CBW 

MOV SI,OFFSET CONTBL 

ADD SI,AX 

ADD SI,AX 

CMP AL, 11 

JA CMDERR 

LES DI,DWORD PTR DS: [BX].TRANS 

PUSH cs 

POP DS 


ASSUME DS:CODE 


IMP WORD PTR [SI] -GO DO COMMAND 
PAGE 
{wT SSS SS SSS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SSS 
= 
-= SUBROUTINES SHARED BY MULTIPLE DEVICES 
_ 
7 pa rn ar pn re rn en pre ne Sp pa he 2 
7 a SNS SD me ORE cee ED GD GD UND cnn GD Gee NERD GD GD GE GED GEES SES GED GEES GED GE Gree GER cues GOED GD eeu SE ce GED eee Ge eee GD Gee SD GE SED NED Ge Se ee ee OP eee oe ae au one 
; 
: EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 
BUSSEXIT: ;DEVICE BUSY EXIT 
MOV AH,000000118 
JMP SHORT ERR1 
CMDERR: 
MOV AL, 3 sUNKNOWN COMMAND ERROR 
ERRSEXIT: 
MOV AH, 10000001B ;MARK ERROR RETURN 
JMP SHORT ERR1 
EXITP PROC FAR 
EXIT: MOV AH, 00000001B 
ERR1L: LDS BX,CS: [PTRSAV] 
MOV WORD PTR [BX] .STATUS,AX ;MARK 


;OPERATION COMPLETE 
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INTRET : 


PAGE 


trylf: 


toroms: 


POP 
POP 
POP 
POP 
POP 
POP 


BREAK KEY HANDLING 


MOV 
IRET 


WARNING - Variables are 
so be careful 


LABEL 
DB 
DB 
dw 


cmp 
jnz 
MOv 
jmp 
cmp 
jz 

cmp 
jnz 


mov 
and 
mov 


CS :ALTAH , 3 


oooo~7WNO 
ie) 


CHROUT - WRITE OUT CHAR IN 


WORD 
00000111B 
0 

Ob800h 


al,13 

trylf 

[col] ,0 
short setit 


al,10 
1f 

al,7 
tryback 


bx, [attrw] 
b1,7 
ah,14 
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;RESTORE REGS AND RETURN 


; INDICATE BREAK KEY SET 


very order dependent, 
when adding. new ones! 


; 0 = WRAP, 1 = NO WRAP 


;Special key handling 


AL USING CURRENT ATTRIBUTE 


;CHARACTER ATTRIBUTE 
;BASE PAGE 
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int 
ret5: ret 


tryback: 


outchr: 


outchrl: 


lf: inc 


setit: mov 


Scroll: call 


mov 


10h 


al,8 

outchr 
[col] ,0 
ret5 

[col] 

Short setit 


bx, [attrw] 
cx,l 

ah,9 

10h 

[col] 

al, [col] 
al, {maxcol] 
setit 
[wrap] ,0 
outchrl 
[col] 


[col] ,0 
[row] 
[row] ,24 
setit 
{row] ,23 
scroll 


dh,row 
d1l,col 
bh,bh 
ah,2 
10h 


getmod 
al,2 
myscroll 
al,3 
myscroll 
al,10 
torom 


bh, [attr] 
bl,' t 
bp, 80 
ax, [base] 
es,ax 
ds,ax 
di,di 
si,160 
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mov 
cld 
cmp 
jz 


rep 
MOv 
mov 
rep 
sret: push 
pop 
ret 


colorcard: 
mov 

wait2: in 
test 
jz 
mov 
mov 
out 
rep 
mov 
mov 
rep 
mov 
mov 
out 
jmp 


GETMOD: MOV 
INT 


CONSOLE 


CONS READ: 
JCXZ 

CONSLOOP: 
PUSH 
CALL 
POP 
STOSB 
LOOP 

CONSEXIT: 
JMP 


Ul 
e 
’ 
e 
c 
e 
a 
C 


HRIN: XOR 


cx, 23*80 


ax,0b800h 
colorcard 


movsw 
ax, bx 
cx,bp 
stosw 
cs 
ds 


dx, 3dah 
al ,dx 
al,8 
wait2 
al,25h 
dx ,3d8h 
dx,al 
mMOvsw 
ax,bx 
cx,bp 
stosw 
al,29h 


AH, 15 


BPAGE , BH 
AH 
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sturn off video 


turn on video 


sget column information 


WORD PTR MODE ,AX 


READ ROUTINE 


CONSEXIT 
CX 

CHRIN 

CX 


CONS LOOP 


AX, AX 


ems SD OU CE CE Ge eee eR GED Ce OEP GED Gene GE GOP See ee oD SED wee Cane Om Gem See eee co eee ee ore com com CU Ge SED Oo ee Gee wee ee oe Soe eee oe SE few ER eee ED oD ome OED ene oom oe 


;SAVE COUNT 
;GET CHAR IN AL 


;STORE CHAR AT ES:DI 


em ee GD eee GED Cm ET SEED ee SEED GD SEND cam Gm GEE Culm GES) Gee CEE SS CeED Gee GD Glee GED enue Se eiew Oe dee OD GND Cee ERD Ge GUN CEN Ge Gow GED SER OD SED GU GED GED oem Se SRD GED GD ED SED ee om ome 


INPUT SINGLE CHAR INTO AL 


MS-DOS DEVICE DRIVERS Page 2-49 


XCHG AL,ALTAH ;GET CHARACTER & ZERO ALTAH 
OR AL,AL 
JNZ KEYRET 
INAGN: XOR AH , AH 
INT 22 
ALT10: 
OR AX , AX ;Check for non-key after BREAK 
JZ INAGN 
OR AL ,AL *SPECIAL CASE? 
JNZ KEYRET 
MOV ALTAH , AH ;STORE SPECIAL KEY 
KEYRET: RET 
6 ee eee ao at ee eee ee See ee oe eee oes 
Ul 
; KEYBOARD NON DESTRUCTIVE READ, NO WAIT 
CONSRDND: 
MOV AL, [ALTAH] 
OR AL,AL 
JNZ RDEXIT 
RD1: MOV AH, 1 
INT 22 
JZ CONBUS 
OR AX,AX 
JNZ RDEXIT 
MOV AH ,0 
INT 22 
JMP CONS RDND 
RDEXIT: LDS BX, [PTRSAV] 
MOV [BX] .MEDIA,AL 
EXVEC: JMP EXIT 
CONBUS: JMP BUSSEXIT 
; 
: KEYBOARD FLUSH ROUTINE 
c 
CONSFLSH: 
MOV [ALTAH] ,0 ;Clear out holding buffer 
PUSH DS 
XOR BP,BP 
MOV DS , BP ;Select segment 0 
MOV DS:BYTE PTR 41AH,1EH ;Reset KB queue head 
;pointer 
MOV DS:BYTE PTR 41CH,1EH ;Reset tail pointer 
POP DS 
JMP EXVEC 


; 
7 
; CONSOLE WRITE ROUTINE 
; 
Cc 


ONSWRIT: 
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CONSLP: 


COUT: 


OUTC: 


JCXZ 
PUSH 
MOV 
XOR 
INT 
MOV 
POP 


MOV 
INC 
CALL 
LOOP 
JMP 


STI 
PUSH 
PUSH 
POP 
CALL 
POP 
IRET 


AH, 3 *SET CURRENT CURSOR POSITION 
WORD PTR [COL] ,DX 

CX 

AL,ES: [DI] GET CHAR 


OUTC ;OUTPUT CHAR 
CONSLP ;REPEAT UNTIL ALL THROUGH 


OUTPUT SINGLE CHAR IN AL TO VIDEO DEVICE 


MOV 
JMP 


CMP 
JNZ 
MOV 
RET 


CALL 
MOV 
RET 


SI,OFFSET STATE 
[ST] 


AL, ESC ;ESCAPE SEQUENCE? 
S1B 
WORD PTR [SI] ,OFFSET S2 


CHROUT 
WORD PTR [STATE] ,OFFSET Sl 


MS-DOS DEVICE DRIVERS 


S2: PUSH AX 
CALL GETMOD 
POP AX 
MOV BX,OFFSET CMDTABL-3 
S7A: ADD BX,3 
CMP BYTE PTR [BX],0 
JZ S1A 
CMP BYTE PTR [BX],AL 
INZ S7A 
JMP WORD PTR [BX+1] 
MOVCUR: CMP BYTE PTR [BX] ,AH 
JZ SETCUR 
ADD BYTE PTR [BX] ,AL 
SETCUR: MOV DX,WORD PTR COL 
XOR BX,BX 
MOV AH, 2 
INT 16 
JMP S1A 
CUP: MOV WORD PTR [SI] ,OFFSET CUP1 
RET 
CUP1: SUB AL, 32 
MOV BYTE PTR [ROW] ,AL 
MOV WORD PTR [SI] ,OFFSET CUP2 
RET 
CUP2: SUB AL, 32 
MOV BYTE PTR [COL] ,AL 
JMP SETCUR 
SM: MOV WORD PTR [SI],OFFSET S1A 
RET 
CUH: MOV WORD PTR COL,0 
JMP SETCUR 
CUF: MOV AH ,MAXCOL 
MOV AL,1 
CUF1: MOV BX,OFFSET COL 
JMP MOVCUR 
CUB: MOV AX, OOF FH 
JMP CUF1 
CUU: MOV AX, OOFFH 
CUU1: MOV BX,OFFSET ROW 
JMP MOVCUR 
CUD: MOV AX, 23*256+1 


JMP CUU1 
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PSCP: MOV 
MOV 
JMP 
PRCP: MOV 
MOV 
JMP 
ED: CMP 
JAE 


MOV 
MOV 
JMP 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
INT 
JMP 


MOV 
RET 
XOR 
MOV 
JMP 


CONSINIT: 
int 
and 
cmp 
jnz 
mov 

iscolor: 
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AX,WORD PTR COL 


SAVCR,AX 
SETCUR 


AX,SAVCR 


WORD PTR COL,AX 


SETCUR 


BYTE PTR [ROW] ,24 


ELI 


CX,WORD PTR COL 


DH, 24 
ERASE 


BYTE PTR [COL] ,0 
CX,WORD PTR [COL] 


DH , CH 

DL ,MAXCOL 
BH,ATTR 
AX ,0600H 
16 

SETCUR 


WORD PTR [SI],OFFSET RM1 


CX ,CX 
CH, 24 
EL2 


11h 


al,00110000b 
al,00110000b 


iscolor 


[base] ,0b000h 


al ,00010000b 


setbrk 
[mode] ,0 


slook for bw card 


:look for 40 col mode 


[maxcol] ,39 


BX,BX 

DS ,BX 
BX,BRKADR 
WORD PTR 
WORD PTR 


BX, 29H*4 
WORD PTR 
WORD PTR 


[BX] ,OF FSET BREAK 
[BX+2],CS 


[BX] ,OFFSET COUT 
[BX+2],CS 


MS-DOS DEVICE DRIVERS Page 2-53 


LDS BX,CS: [PTRSAV] 
MOV WORD PTR [BX].TRANS,OFFSET CONSINIT 
;SET BREAK ADDRESS 
MOV [BX] .TRANS+2,CS 
JMP EXIT 
CODE ENDS 


END 
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CHAPTER 3 


MS-DOS TECHNICAL INFORMATION 


3.1 MS-DOS INITIALIZATION 


MS-DOS initialization consists of several steps. Typically, 
a ROM (Read Only Memory) bootstrap obtains control, and then 
reads the boot sector off the disk. The boot sector’ then 
reads the following files: 


IO0.SYS 
MSDOS ..SYS 


Once these files are read, the boot process begins. 


3.2 THE COMMAND PROCESSOR 


The command processor supplied with MS-DOS (file 
COMMAND.COM.) consists of three parts: 


1. 


2 


A resident part resides in memory immediately 
following MSDOS.SYS and its data area. This part 
contains routines’ to process Interrupts 23H 
(Control-C Exit Address) and 24H (Critical Error 
Handler Address), aS well as a routine to reload 
the transient part, if needed. All standard MS-DOS 
error handling is done within this part of 
COMMAND .COM. This includes displaying error 
messages and processing the Abort, Retry, or Ignore 
messages. 


An initialization part follows the resident part. 
During startup, the initialization part is given 
control; it contains the AUTOEXEC file processor 
setup routine. The initialization part determines 
the segment address at which programs can _ be 
loaded. It is overlaid by the first program 
COMMAND.COM loads because it is no longer needed. 
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3. A transient part is loaded at the high end of 


memory. This part contains all of the internal 
command processors and the batch file processor. 


The transient part of the command processor 
produces the system prompt (such as A>), reads the 
command from keyboard (or batch file), and causes 
it to be executed. For external commands, this 
part builds a command line and issues the EXEC 
system call (Function Request 4B00H) to load and 
transfer control to the program. 


3.3 MS-DOS DISK ALLOCATION 
The MS-DOS area is formatted as follows: 


Reserved area - variable size ~ 
First copy of file allocation | 
table - variable size 


Additional copies of file 
allocation table - variable 
size (optional) 


Root directory - variable size’ 


File data area 


Space for a file in the data area is not pre-allocated. The 
Space is allocated one cluster at ae time. A cluster 
consists of one or more consecutive sectors (the number of 
sectors in a cluster must be a power of 2); The cluster 
size is determined at format time. All of the clusters’ for 
a file are "chained" together in the File Allocation Table 
(FAT). (Refer to Section 3.5, "File Allocation Table," for 
more information on the FAT.) A second copy of the FAT is 
normally kept for consistency except in the case of 
extremely reliable storage such as a virtual RAM disk. 
Should the disk develop a bad sector in the middle of the 
first FAT, the second can be used. This avoids loss of data 
due to an unreadable FAT. 


3.4 MS-DOS DISK DIRECTORY 


FORMAT builds the root directory for all disks. Its 
location on disk and the maximum number of entries are 
dependent on the media. 
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Since directories other than 
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the root directory are regarded 


as files by MS-DOS, there is no limit to the number of files 
they may contain. 


All directory entries are 32 


following format (note that byte offsets are 
hexadecimal): 


0-7 


8-0A 


OB 


Filename. Eight characters, left aligned and 
padded, if necessary, with blanks. The first 
byte of this field indicates the file status 
as follows: 


00H The directory entry has never been 
used. This is used to limit the 
length of directory searches, for 
performance reasons. 


05H Indicates that the first character 
of the filename actually has an E5H 
character. 


2EH The entry is for a directory. If 
the second byte is also 2EH, 
then the cluster field contains 
the cluster number of this 
directory's parent directory 
(OOOOH if the parent directory 
is the root directory). Other- 
wise, bytes 01H through OAH 
are all spaces, and the cluster 
Field contains the cluster 
number of this directory. 


E5H The file was used, but it has been 
erased. 


Any other character is the first character 
of a filename. 


Filename extension. 


File attribute. The attribute byte is 
mapped as follows (values are in hexa- 
decimal): 


01 File is marked read-only. An attempt 
to open the file for writing using 
the Open Handle system call (Function 
Request 3DH) results in an error 
code being returned. This value 
can be used along with other 
values below. Attempts to delete 
the file with the Delete File 
system call (13H) or Delete 


bytes in length, and are in the 


in 
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0C-15 


16-17 


02 


04 


08 


10 


20 


Directory Entry (41H) will also 
fail. 


Hidden file. The file is excluded 
from normal directory searches. 


System file. The file is excluded 
from normal directory searches. 


The entry contains the volume label 
in the first 1l bytes. The entry 
contains no other usable information 
(except date and time of creation), 
and may exist only in the root 
directory. 


The entry defines a subdirectory, 
and is excluded from normal 
directory searches. 


Archive bit. The bit is set to "on" 
whenever the file has been written 
to and closed. 


Note: The system files (IO.SYS and 
MSDOS.SYS) are marked as read-only, 
hidden, and system files. Files can 
be marked hidden when they are created. 
Also, the read-only, hidden, system, 
and archive attributes may be changed 
through the Get/Set File Attributes 
system call (Function Request 43H). 


RESERVED. 


Time the file was created or last updated. 
The hour, minutes, and seconds are mapped 

into two bytes as follows (bit 7 on left, 

0 on right): 


Offset 17H 
|H|H|H| HI] H|M[M[ MM | 


Offset 16H 
M|M|mM|S|S|]S|]S|sS | 


where: 


H 
M 
S) 


is the binary number of hours (0-23) 
is the binary number of minutes (0-59) 
is the binary number of two-second 
increments 
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18-19 Date the file was created or last updated. 
The year, month, and day are mapped into two bytes 
as follows: 


Offset 19H 
Poe eb eee el eae a 


Offset 18H 
|mM{[mM|[M{[D|]dD|[dD|DI|{DI| 


where: 

4 is 0-119 (1980-2099) 
M is 1-12 
D is 1-31 


1A-1B Starting cluster; the cluster number 
of the first cluster in the file. 


Note that the first cluster for data space 
on all disks is cluster 002. 


The cluster number is stored with the 
least significant byte first. 


Note 


Refer to Sections 3.5.1 and 3.5.2 for details about 
converting cluster numbers to logical sector numbers. 


1C-1F File size in bytes. The first word of this 
four-byte field is the low-order part of 
the size. 


3.5 FILE ALLOCATION TABLE (FAT) 


The following information is included for system programmers 
who wish to write installable device drivers. This section 
explains how MS-DOS uses the File Allocation Table to 
convert the clusters of a file to logical sector numbers to 
allocate disk space for a file. The driver is’ then 
responsible for locating the logical sector on disk. 
Programs should use the MS-DOS file management’ function 
calls for accessing files; programs that access the FAT are 
not guaranteed to be upwardly-compatible with future 
releases of MS-DOS. 


The File Allocation Table is an array of 12-bit entries (1.5 
bytes) for each cluster on the disk. For disks containing 
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more than 4085 (note that 4085 is the correct number) 
clusters, a 16-bit FAT entry is used. 


The first byte may be used by the device driver as a FAT ID 
byte for media determination. The first two FAT entries are 
reserved. 


The third FAT entry, which starts at byte offset 4, begins 
the mapping of the data area (cluster 002). Files in the 
data area are not always written sequentially on the disk. 
The data area is allocated one cluster at a time, skipping 
over clusters already allocated. The first free cluster 
following the last cluster allocated for that file will be 
the next cluster allocated, regardless of its physical 
location on the _ disk. This permits the most efficient 
utilization of disk space because clusters made available by 
erasing files can be allocated for new files. 


Each FAT entry contains three or four hexadecimal characters 
depending on whether it is a 12- or 16-bit entry: 


(0)000 If the cluster is unused and available. 


(F) FF7 The cluster has a bad sector in it if this 
cluster is not part of any cluster chain. 
MS-DOS will not allocate such a cluster. 
Chkdsk counts the number of bad clusters 
for its report. These bad clusters are 
not part of any allocation chain. 


(F)FF8-FFF Indicates the last cluster of a file. 


(X) XXX Any other characters that are the cluster 
number of the next cluster in the file. 
The cluster number of the first cluster 
in the file is kept in the file's directory 
entry. 


The File Allocation Table always begins on the first sector 
after the reserved sectors. If the FAT is larger than one 
sector, the sectors are contiguous. Two copies of the FAT 
are usually written for data integrity. The FAT is read 
into one of the MS-DOS buffers whenever needed (open, read, 
write, etc.). For performance reasons, this buffer is given 
a high priority to keep it in memory as long as possible. 


3.5.1 How To Use the PAT (12-bit PAT Entries) 


Use the directory entry to find the starting cluster of the 
file. Next, to locate each subsequent cluster of the file: 
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ds 


Multiply the cluster number just used by 1.5 (each 
FAT entry is 1.5 bytes long). 


The whole part of the product is an offset into the 
FAT, pointing to the entry that maps the cluster 
just used. That entry contains the cluster number 
of the next cluster of the file. 


Use a MOV instruction to move the word at the 
calculated FAT offset into a register. 


If the last cluster used was an even number, keep 
the low-order 12 bits of the register by ANDing it 
with FFF; otherwise, keep the high-order 12 bits 
by shifting the register right 4 bits with a SHR 
instruction. 


Tf the resultant 12 bits are FF8H-FFFH, the file 
contains no more clusters. Otherwise, the 12 bits 
contain the cluster number of the next cluster in 
the file. 


To convert the cluster to a logical sector number (relative 


sector, 
DEBUG) : 


such as that used by Interrupts 25H and 26H and by 


Subtract 2 from the cluster number. 


Multiply the result by the number of sectors’ per 
cluster. 


Add to this result the logical sector number of the 
beginning of the data area. 


3.5.2 How To Use The FAT (16-bit FAT Entries) 


Use the directory entry to get the starting cluster of the 


file. 


1. 


To find the next file cluster: 


Multiply the cluster number used by 2 (each FAT 
entry is 2 bytes). 
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2. Use a MOV WORD instruction to move the word at’ the 
calculated FAT offset into a register. 


3. If the resultant 16 bits are FFF8-FFFFH, then there 
are no more clusters in the file. Otherwise, the 
16 bits contain the cluster number of the next | 
cluster at the file. | 


3.6 MS-DOS STANDARD DISK FORMATS 


On an MS-DOS disk, it is recommended that the clusters’ be 
arranged on disk to minimize head movement for multi-sided 
media. All of the space on ae track (or cylinder) is 
allocated before moving on to the next track. This is 
accomplished by using the sequential sectors on the 
lowest-numbered head, then all the sectors on the next head, 
and so on, until all sectors on all heads of the track are 
used. The next sector to be used will be sector 1 on head 0 
of the next track. 


The formats in Table 3.1 are considered to be standard and 
should be readable if at all possible. 
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Table 3.1 MS-DOS Standard Disk Formats 


Disk Size (in inches) 3-1/2 or 5-1/4 5-1/4 8 


Number of tracks 80 80 80 80 40 40 40 40 80 77 77 #77 


3 byte JUMP 
8 byte name 


WORD bytes/sector 00 00 00 00 00 00 00 00 00 80 80 00 
02 02 02 02 O02 02 02 02 02 O00 00 04 
BYTE cluster size 02 02 02 02 O1 02 01 02 O01 O04 04 O1 


WORD reserved sectors 01 01 01 01 O01 010101 01 O01 04 O1 


BYTE # FATS 02 02 02 02 O02 02 02 02 02 O02 02 02 
WORD # Dir entries 70 70 70 70 40 70 40 70 EO 44 44 CO 
00 00 00 00 00 00 00 00 00 OO 00 O00 
WORD # Sectors DO AO 80 00 68 DO 40 80 60 D2 D2 68 
02 05 02 05 O1 02 O01 02 09 O7 O07 02 
BYTE media F8 F9 FA FB’ FC FD FE FF F9 FE FD FE 
WORD sectors/FAT 02 03 01 02 O02 02 O01 01 07 O06 06 02 
00 00 00 00 00 00 00 00 00 OO O00 O00 
WORD sectors/track 09 09 08 08 O9 09 08 O08 OF 1A IA 08 
00 00 00 00 O00 00 00 00 00 O00 O00 OD 
WORD # heads 01 02 01 02 O1 02 01 02 02 O1 O01 02 


WORD hidden sectors 00 00 00 00 00 00 00 00 00 O00 00 00 


BOTS 
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CHAPTER 4 


MS-DOS CONTROL BLOCKS AND WORK AREAS 


4.1 TYPICAL MS-DOS MEMORY MAP 
Interrupt vector table 
Optional extra space (used by IBM for ROM data area) 
IO.SYS - MS-DOS interface to hardware 


MSDOS.SYS - MS-DOS interrupt handlers, service routines 
(Interrupt 21H functions) 


MS-DOS buffers, control areas, and installed device 
drivers 


Resident part of COMMAND.COM - Interrupt handlers’ for 
Interrupts 22H (Terminate Process Exit Address), 23H 
(Control-C Handler Address), 24H (Critical Error 
Handler Address) and code to reload the transient part 


External command or utility - (.COM or .EXE file) 
User stack for .COM files (256 bytes) 


Transient part of COMMAND.COM - Command interpreter, 
internal commands, batch processor 


User memory is allocated from the lowest end of available 
memory that will meet the allocation request. 
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4.2 MS-DOS PROGRAM SEGMENT 


When an external command is typed, or when you execute a 
program through the EXEC system call, MS-DOS determines the 
lowest available free memory address to use as the start of 
the program. This area is called the Program Segment. 


The first 256 bytes of the Program Segment are set up by the 
EXEC system call for the program being loaded into memory. 
The program is then loaded following this’ block. An .EXE 
file with minalloc and maxalloc both set to zero is loaded 
as high as possible. 


At offset 0 within the Program Segment, MS-DOS builds’ the 
Program Segment Prefix control block. The program returns 
from EXEC by one of five methods: 

1. By issuing an Interrupt 21H with AH=4CH 


2. By issuing an Interrupt 21H with AH=31H (Keep 
Process) 


3. A long jump to offset 0O in the Program Segment 
Prefix 


4. By issuing an Interrupt 20H with CS:0 pointing at 
the PSP 


5. By issuing an Interrupt 21H with register AH=0 and 
with CS:0 pointing at the PSP. 


Note 


Methods 1 and 2 are preferred for both functionality 
and best operation in future versions of MS-DOS. 


All five methods result in transferring control to the 
program that issued the EXEC. Using method 1 or 2 allows a 
completion code to be returned. During this returning 
process, Interrupts 22H, 23H, and 24H (Terminate Process 
Exit Address, Control-C Handler Address, and Critical Error 
Handler Address) addresses are restored from the values 
saved in the Program Segment Prefix of the terminating 
program. Control is then given to the terminate address. 
If this is a program returning to COMMAND.COM, control 
transfers to its resident portion. If a batch file was in 
process, it is continued; otherwise, COMMAND.COM performs a 
checksum on the transient part, reloads it if necessary, 
then issues the system prompt and waits for you to type’ the 
next command. 
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When a program receives control, the following conditions 
are in effect: 


For all programs: 


The segment address of the passed environment is 
contained at offset 2CH in the Program Segment 
Prefix. 


The environment is a series of ASCII strings 
(totaling less than 32K) in the form: 


NAME=parameter 


Each string is terminated by a byte of zeros, and 
the set of strings is terminated by another byte of 
zeros. 


Following the last byte of zeros is ae set of 
initial arguments passed to a program that contains 
a word count followed by an ASCIZ string. If the 
file is found in the current directory, the ASCIZ 
string contains the drive and pathname of the 
executable program as passed to the EXEC function 
call. If the file is found in the path, the 
filename is concatenated with the information in 
the path. Programs may use this area to determine 
where the program was loaded. 


The environment built by the command _ processor 
contains at least a COMSPEC= string (the parameters 
on COMSPEC define the path used by MS-DOS to locate 
COMMAND.COM on disk). The last Path and Prompt 
commands issued will also be in the environment, 
along with any environment strings defined with the 
MS-DOS Set command. 


The environment that is passed is a copy of the 
invoking process environment. If your application 
uses a "keep process" concept, you should be aware 
that the copy of the environment passed to you is 
static. That is, it will not change even if 
subsequent Set, Path, or Prompt commands are 
issued. Conversely, any modification of the passed 
environment by the application will not _ be 
reflected in the parent process environment. For 
instance, a program cannot change the MS-DOS 
environment values as the Set command does. 


The Disk Transfer Address (DTA) is set to 80H 
(default DTA in the Program Segment Prefix). At 
5CH and 6CH in the Program Segment Prefix are file 
control blocks. These are formatted from the first 
two parameters, typed when the command was entered. 
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If either parameter contained a pathname, then the 
corresponding FCB contains only the valid drive 
number. The filename field will not be valid. 


An unformatted parameter area at 81H contains all 
the characters typed after the command (including 
leading and imbedded delimiters), with the byte at 
80H set to the number of characters. If the <, >, 
Or parameters were typed on the command line, they 
(and the filenames associated with them) will not 
appear in this area; redirection of standard input 
and output is transparent to applications. 


Offset 6 (one word) contains the number of bytes 
available in the segment. 


Register AX indicates whether or not the drive 
Specifiers (entered with the first two parameters) 
are valid, as follows: 


AL=FF if the first parameter contained an 
invalid drive specifier (otherwise AL=00) 


AH=FF if the second parameter contained an 
invalid drive specifier (otherwise AH=00) 


Offset 2 (one word) contains the segment address of 
the first byte of unavailable memory. Programs 
must not modify addresses beyond this point unless 
they were obtained by allocating memory via the 
Allocate Memory system call (Function Request 48H). 


For Executable (.EXE) programs: 


DS and ES registers are set to point to the Program 
Segment Prefix. 


CS,IP,SS, and SP registers are set to the values 
set by MS-LINK in the .EXE image. 


For Executable (.COM) programs: 


All four segment registers contain the segment 
address of the initial allocation block that starts 
with the Program Segment Prefix control block. 


All of user memory is allocated to the program. If 
the program invokes another program through 
Function Request 4BH, it must first free some 
memory through the Set Block (4AH) function call, 
to provide space for the program being executed. 


The Instruction Pointer (IP) is set to 100H. 
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The Stack Pointer register is set to the end of the 
program's segment. The segment size at offset 6 is 
reduced by 100H to allow for a stack of that size. 


A word of zeros is placed on top of the stack. 
This is to allow a user program to exit to 
COMMAND.COM by doing a RET instruction last. This 
assumes, however, that the user has maintained his 
stack and code segments. 


Figure 4.1 illustrates the format of the Program Segment 
Prefix. All offsets are in hexadecimal. 
(Offsets in Hex) 
Long Offset add 


INT 20H call Function 
(5 bytes) dispatcher 


Segment addr. Terminate address Control-C exit 


Function (IP, CS) address (IP) 
dispatcher 


Control-C Hard error exit address 
exit (IP, CS) 
address (CS) 


Used by MS-DOS 


5CH 


Formatted Parameter Area 1 formatted as standard 
unopened FCB 6CH 


Formatted Parameter Area 2 formatted as standard 
unopened FCB (overlaid if FCB at 5CH is opened) 


Unformatted Parameter Area 
(default Disk Transfer Area) 
Initially contains command invocation line. 


100 
Figure 4.1 Program Segment Prefix 
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Important 


Programs must not alter any part of the Program Segment 
Prefix below offset 5CH. 


Chapter 5 
EXE File Structure and Loading 


CHAPTER 5 


-EXE FILE STRUCTURE AND LOADING 


Note 


This chapter describes .EXE file structure and loading 
procedures for systems that use a version of MS-DOS 


that is lower than 2.0. For MS-DOS 2.0 and higher, use 
Function Request 4B00H, Load and Execute a Program, to 
load (or load and execute) an .EXE file. 


The .EXE files produced by the Microsoft(R) Linker (MS-LINK) 
consist of two parts: 


Control and relocation information 

The load module 
The control and relocation information is at the beginning 
of the file in an area called the header. The load module 


immediately follows the header. 


The header is formatted as follows. (Note that offsets are 
in hexadecimal.) 


Offset Contents 
00-01 Must contain 4DH, 5AH. 


02-03 Number of bytes contained in last page; 
| this is useful in reading overlays. 


04-05 Size of the file in 512-byte pages, 
including the header. 


06-07 Number of relocation entries in table. 


08-09 Size of the header in 16-byte paragraphs. 


-EXE FILE STRUCTURE AND LOADING Page 5-2 


This is used to locate the beginning of 
the load module in the file. 


OA-OB Minimum number of 16-byte paragraphs 
required above the end of the loaded 
program. 


0C-OD Maximum number of 16-byte paragraphs 
required above the end of the loaded 
program. If both minalloc and max- 
alloc are 0, then the program will 
be loaded as high as possible. 


OE-OF Initial value to be loaded into stack 
segment before starting program exe- 
cution. This must be adjusted by 


relocation, 

10-11 Value to be loaded into the SP register 
before starting program execution. 

12-13 Negative sum of all the words in the 
file. 

14-15 Initial value to be loaded into the IP 
register before starting program 
execution. 

16-17 Initial value to be loaded into the CS 


register before starting program 
execution. This must be adjusted by 


relocation. 

18-19 Relative byte offset from beginning of 
run file to relocation table. 

1A-1B The number of the overlay as generated by 
MS-LINK. 


The relocation table follows the formatted area described 
above. This table consists of a variable number of 
relocation items. Each relocation item contains two fields: 
a two-byte offset value, followed by a two-byte segment 
value. These two fields contain the offset into the load 
module of a word which requires modification before the 
module is given control. The following steps describe this 
process: 


1. The formatted part of the header is read into 
memory. Its size is 1BH. 
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2. 


A portion of memory is allocated depending on the 
Size of the load module and the allocation numbers 
(OA-OB and OC-OD). MS-DOS attempts to allocate 
FFFFH paragraphs. This will always fail, returning 
the size of the largest free block. If this block 
is smaller than minalloc and loadsize, then there 
will be no memory error. If this block is larger 
than maxalloc and loadsize, MS-DOS will allocate 
(maxalloc + loadsize). Otherwise, MS-DOS will 
allocate the largest free block of memory. 


A Program Segment Prefix is built in the lowest 
part of the allocated memory. 


The load module size is calculated by subtracting 
the header size from the file size. Offsets 04-05 
and 08-09 can be used for this calculation. The 
actual size is downward-adjusted based on _ the 
contents of offsets 02-03. Based on the setting of 
the high/low loader switch, an appropriate segment 
is determined at which to load the load module. 
This segment is called the start segment. 


The load module is read into memory beginning with 
the start segment. 


The relocation table items are read into a work 
area. 


Each relocation table item Segment value is added 
to the start segment value. This calculated 
segment, plus the relocation item offset value, 
points to a word in the load module to which is 
added the start segment value. The result is 
Placed back into the word in the load module. 


Once all relocation items have been processed, the 
SS and SP registers are set from the values in the 
header. Then, the start Segment value is added to 
SS. The ES and DS registers are set to the segment 
address of the Program Segment Prefix. The start 
segment value is added to the header CS register 
value. The result, along with the header IP value, 
is the initial CS:IP to transfer to before starting 
execution of the program. 


Chapter 6 
Intel Relocatable Object Module Formats 


6.1 Introduction 6-1 

6.2 Definition of Terms 6-2 

6.3 Module Identification and Attributes 6-4 
6.4 Segment Definition 6-4 

6.5 Segment Addressing 6-5 

6.6 Symbol Definition 6-6 

6.7 Indices 6-7 

6.8 Conceptual Framework for Fixups 6-8 
6.9 Self-Relative Fixups 6-13 

6.10 Segment-Relative Fixups 6-14 

6.11 Record Order 6-14 

6.12 Introduction to the Record Formats 6-16 
6.13 Numeric List of Record Types 6-47 


6.14 Microsoft Type Representations for Communal 
Variables 6-48 


CHAPTER 6 


INTEL RELOCATABLE OBJECT MODULE FORMATS 


6.1 INTRODUCTION 


This chapter presents the object record formats that define 
the relocatable object language for the 8086 microprocessor. 
The 8086 object language is the output of all language 
translators that have the 8086 as the target processor and 
are to be linked using the Microsoft Linker. The 8086 
Object language is input and output for object language 
processors such as linkers and librarians. 


The 8086 object module formats permit you to specify 
relocatable memory images that may be linked together. 
Capabilities are provided that allow efficient use of the 
memory mapping facilities of the 8086 microprocessor. 


The following table lists the record formats that are 
Supported by Microsoft. These record formats are described 
in this chapter. Record formats that are preceded by an 
asterisk (*) deviate from the Intel(R) specification. 
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Table 6.1 Object Module Record Formats 


T-MODULE HEADER RECORD 
LIST OF NAMES RECORD 
*SEGMENT DEFINITION RECORD 
*GROUP DEFINITION RECORD 
*TYPE DEFINITION RECORD 


Symbol Definition Records 
*PUBLIC NAMES DEFINITION RECORD 
*EXTERNAL NAMES DEFINITION RECORD 
*LINE NUMBERS RECORD 


Data Records 
LOGICAL ENUMERATED DATA RECORD 
LOGICAL ITERATED DATA RECORD 


FIXUP RECORD 


*MODULE END RECORD 
COMMENT RECORD 


6.2 DEFINITION OF TERMS 
The following terms are fundamental to the 8086 relocation 
and linkage. 


OMF - Object Module Formats. 


MAS - Memory Address Space. The 8086 MAS is 1 megabyte 
(1,048,576). Note that the MAS is distinguished from actual 
memory, which may occupy only a portion of the MAS. 


MODULE - an "inseparable" collection of object code and 
other information produced by a translator. 


T-MODULE - A module created by a translator, such as’ Pascal 
Or FORTRAN. 


{ 
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The following restrictions apply to object modules: 


1. Every module should have a name. Translators’ will 
provide names for T-modules, providing a default 
name (possibly the filename or a null name) if 
neither Source code nor user specifies otherwise. 


2. Every T-module in a collection of linked modules 
must have a different name, so that symbolic 
debugging systems can distinguish the various’ line 
numbers and local symbols. This restriction is not 
required by the Linker, and is not enforced by it. 


FRAME - A contiguous region of 64K of MAS, beginning on a 
paragraph boundary (i.e., on a multiple of 16 bytes). This 
concept is useful because the content of the four 8086 
segment registers defines four (possibly overlapping) 
FRAMES; no 16-bit address in the 8086 code can access a 
memory location outside of the current four FRAMES. 


LSEG - Logical Segment - A contiguous region of memory whose 
contents are determined at translation time (except for 
address-binding). Neither size nor location in MAS are 
necessarily determined at translation time: size, although 
partially fixed, may not be final because the LSEG may be 
combined at LINK time with other LSEGs, forming a single 
LSEG. An LSEG must not be larger than 64K, so that it can 
fit in a FRAME. This means that any byte in an LSEG may be 
addressed by a 16-bit offset from the base of a FRAME 
covering the LSEG. 


PSEG - Physical Segment - This term is equivalent to FRAME. 
Some people prefer "PSEG" to "FRAME" because the terms 
"PSEG" and "LSEG" reflect the "physical" and "logical" 
nature of the underlying segments. 


FRAME NUMBER - Every FRAME begins on a paragraph boundary. 
The "paragraphs" in MAS can be numbered from 0 through 
65535. These numbers, each of which defines a FRAME, are 
called FRAME NUMBERS. 


PARAGRAPH NUMBER - This term is equivalent to FRAME NUMBER. 


PSEG NUMBER - This term is equivalent to FRAME NUMBER. 
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GROUP - A collection of LSEGs defined at translation time, 
whose final locations in MAS have been constrained such that 
there will be at least one FRAME that covers’ (contains) 
every LSEG in the collection. 


The notation "Gr A(X,Y,Z,)" means that LSEGs X, Y and Z form 
a group whose name is A. The fact that X, Y and Z are all 
LSEGs in the same group does not imply any ordering of X, Y 
and Z in MAS, nor does it imply any contiguity between X, Y 


renee ee OR 6 


The Microsoft Linker does not currently allow an LSEG to be 
a member of more than one group. The Linker will ignore all 
attempts to place an LSEG in more than one group. 


CANONIC - Any location in MAS is contained in exactly 4096 
distinct FRAMES; but one of these FRAMES can be 
distinguished because it has a higher FRAME NUMBER. This 
distinguished FRAME is called the canonic FRAME of the 
location. In other words, the canonic frame of a given byte 
is the frame so chosen that the byte's offset from that 
frame lies in the range 0 to 15 (decimal). Thus, if FOO is 
a symbol defining a memory location, one may speak of the 
"Canonic FRAME of FOO", or of "FOO'S canonic FRAME". By 
extension, if S is any set of memory locations, then there 
exists a unique FRAME which has the lowest FRAME NUMBER in 
the set of canonic FRAMES of the locations in S. This 
unique FRAME is called the canonic FRAME of the set S. 
Thus, we may speak of the canonic FRAME of an LSEG or of a 
group of LSEGs. 


SEGMENT NAME -—- LSEGS are assigned segment names at 
translation time. These names serve two purposes: 


1. They play a role at LINK time in determining which 
LSEGs are combined with other LSEGs. 


2. They are used in assembly source code to. specify 
groups. 


CLASS NAME - LSEGs may optionally be assigned Class Names at 
translation time. Classes define a partition on LSEGs: two 
LSEGS are in the same class if they have the same Class 
Name. 


The Microsoft Linker applies the following semantics’ to 
class names. The class name "CODE" or any class name whose 
suffix is "CODE" implies that all segments of said class 
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contain only code and may be considered read-only. Such 
segments may be overlayed if the user specifies the module 
containing the segment as part of an overlay. 


OVERLAY NAME - LSEGS may optionally be assigned an overlay 
name. The overlay name of an LSEG is ignored by MS-LINK 
(version 2.40 and later versions), but it is used by Intel 
Relocation and Linkage products. 


COMPLETE NAME - The complete name of an LSEG consists of the 
Segment Name, Class Name, and Overlay Name. LSEGs from 
different modules will be combined if their Complete Names 
are identical. 


6.3 MODULE IDENTIFICATION AND ATTRIBUTES 


A module header record is always the first record in a 
module. It provides a module name. 


In addition to a name, a module may have the attribute of 
being a main program as well as having a specified starting 
address. When linking multiple modules together, only one 
module with the main attribute should be given. 


In summary, modules may Or may not be main and may or _ may 
not have a starting address. 


6.4 SEGMENT DEFINITION 


A module is a collection of object code defined by a 
sequence of records produced by a translator. The object 
code represents contiguous regions of memory whose _ contents 
are determined at translation time. These regions are 
called LOGICAL SEGMENTS (LSEGs). A module defines’ the 
attributes of each LSEG. The SEGMENT DEFINITION RECORD 
(SEGDEF) is the vehicle by which all LSEG information (name, 
length, memory alignment, etc.) is maintained. The LSEG 
information is required when multiple LSEGs are combined and 
when segment addressability (See Section 6.5, "Segment 
Addressing") is established. The SEGDEF records are 
required to follow the first header record. 
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6.5 SEGMENT ADDRESSING 


The 8086 addressing mechanism provides segment base 
registers from which a 64K-byte region of memory, called a 
FRAME, may be addressed. There is one code segment’ base 
register (CS), two data segment base registers (DS, ES), and 
one stack segment base register (SS). 


The possible number of LSEGs that may make up a memory image 
far exceeds the number of available base registers. Thus, 
base registers may require frequent loading. This would be 
the case in a modular program with many small data and/or 
code LSEGs. 


Since such frequent loading of base registers is 
undesirable, it is a good strategy to collect many small 
LSEGs together into a single unit that will fit in one 
memory frame so that all the LSEGsS may be addressed using 
the same base register value. This addressable unit is a 
GROUP and has been defined earlier in Section 6.2, 
"Definition of Terms." 


To allow addressability of objects within a GROUP to be 
established, each GROUP must be explicitly defined in the 
module. The GROUP DEFINITION RECORD (GRPDEF) provides a 
list of constituent segments either by segment name or by 
segment attribute such as "the segment defining symbol FOO" 
or "the segments with class name ROM." 


The GRPDEF records within a module must follow all SEGDEF 
records as GRPDEF records may reference SEGDEF records in 
defining a GROUP. The GRPDEF records must also precede all 
other records except header records, as the Linker must 
process them first. 


6.6 SYMBOL DEFINITION 


MS-LINK supports three different types of records that fall 
into the class of symbol definition records. The two most 
important types are PUBLIC NAMES DEFINITION RECORDS 
(PUBDEFs) and EXTERNAL NAMES DEFINITION RECORDS (EXTDEFsS). 
These types are used to define globally visible procedures 
and data items and to resolve external references. [In 
addition, TYPDEF records are used by MS-LINK for the 
allocation of communal variables (see Section 6.14 
"Microsoft Type Representations for Communal Variables"). 
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6.7 INDICES 


"Index" fields occur throughout this document. An index is 
an integer that selects some particular item from a 
collection of such items. (List of examples: NAME INDEX, 
SEGMENT INDEX, GROUP INDEX, EXTERNAL INDEX, TYPE INDEX.) 


Note 


An index is normally a positive number. The index 
value zero is reserved, and may carry a special meaning 


dependent upon the type of index (e.g., a Segment Index 
of zero specifies the "Unnamed," absolute pseudo- 
segment; a Type Index of zero specifies the "Untyped 
type", which is different from "Decline to state"). 


In general, indices must assume values quite large (that is, 
much larger than 255). Nevertheless, a great number of 
object files will contain no indices with values greater 
than 50 or 100. Therefore, indices will be encoded in one 
Or two bytes, as required. 


The high-order (left-most) bit of the first (and possibly 
the only) byte determines whether the index occupies one 
byte or two. If the bit is 0, then the index is a _ number 
between OQ and 127, occupying one byte. If the bit is l, 
then the index is a number between 0 and 32K-1, occupying 
two bytes, and is determined as follows: the low-order 8 
bits are in the second byte, and the high-order 7 bits are 
in the first byte. 


INTEL RELOCATABLE OBJECT MODULE FORMATS Page 6-8 


6.8 CONCEPTUAL FRAMEWORK FOR FIXUPS 
A "fixup" is some modification to object code, requested by 


a translator, performed by the Linker, achieving address 
binding. 


Note 


This definition of "fixup" accurately represents the 
viewpoint maintained by the Linker. Nevertheless, the 
Linker can be used to achieve modifications of object 
code (i.e., "fixups") that do not conform to this 
definition. For example, the binding of code to either 


hardware floating point or software floating point 
subroutines is a modification to an operation code, 
where the operation code is treated as if it were an 
address. The previous definition of "fixup" is not 
intended to disallow or disparage object code 
modifications. 


8086 translators specify a fixup by giving four data: 


1. The place and type of a LOCATION to be fixed up. 


2. One of two possible fixup MODEs. 


3. A TARGET, which iS a memory address to which 
LOCATION must refer. 


4, A FRAME defining a context within which the 
reference takes place. 


LOCATION - There are 5 types of LOCATION: a POINTER, a 
BASE, an OFFSET, a HIBYTE, and a LOBYTE. 


The vertical alignment of the following figure illustrates 
four points. (Remember that the high-order byte of a word 
in 8086 memory is the byte with the higher address.) 


1. A BASE is the high-order word of a pointer (and the 
Linker doesn't care if the low-order word of the 
pointer is present or not). 
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2. An OFFSET is the low-order word of a pointer (and 
the Linker doesn't care if the high-order word 
follows or not). 


3. A HIBYTE is the high-order half of an OFFSET (and 
the Linker doesn't care if the low-order half 
precedes or not). 


4. A LOBYTE is the low-order half of an OFFSET (and 


the Linker doesn't care if the high-order half 
follows or not). 


Base: | 
Hibyte: | | 
Lobyte: | | 


Figure 6.1 LOCATION Types 


A LOCATION is specified by two data: (1) the LOCATION type, 
and (2) where the LOCATION is. The first is specified by 
the LOC subfield of the LOCAT field of the FIXUP record; 


the second is specified by the DATA RECORD OFFSET subfield 
of the LOCAT field of the FIXUP record. 


MODE - The Linker supports two kinds of fixups: 
"self-relative" and "Segment-relative." 


Self-relative fixups support the 8- and 16-bit offsets that 
are used in the CALL, JUMP and SHORT-JUMP instructions. 


‘\. Segment-relative fixups Support all other addressing modes 


of the 8086. 
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TARGET - The TARGET is the location in MAS being referenced. 
(More explicitly, the TARGET may be considered to be the 
lowest byte in the object being referenced.) A TARGET is 
specified in one of eight ways. There are four "primary" 
ways, and four "secondary" ways. Each primary way of 
specifying a TARGET uses two kinds of data: an. 
INDEX-or-FRAME-NUMBER 'X', and a displacement 'D'. | 


(TO) X is a SEGMENT INDEX. The TARGET is the Dth 
byte in the LSEG identified by the INDEX. 


(Tl) X is a GROUP INDEX. The TARGET is the Dth 
byte in the LSEG identified by the INDEX. 


(T2) X is an EXTERNAL INDEX. The TARGET is the Dth 
byte following the byte whose address is 
(eventually) given by the External Name identified 
by the INDEX. 


(T3) X is a FRAME NUMBER. The TARGET is the Dth 
byte in the FRAME identified by the FRAME NUMBER 
(i.e., the address of TARGET is (X*16)+D). 


Each secondary way of specifying a TARGET uses only one data 
item: the INDEX-or-FRAME-NUMBER X. An implicit 
displacement equal to zero is assumed. 


(T4) X is a SEGMENT INDEX. The TARGET is the Oth 
(first) byte in the LSEG identified by the INDEX. 


(T5) X is a GROUP INDEX. The TARGET is the Oth 
(first) byte in the LSEG in the specified group 
that is eventually LOCATEd lowest in MAS. 


(T6) X iS an EXTERNAL INDEX. The TARGET is’ the 
byte whose address is the External Name identified 
by the INDEX. 


(T7) X is a FRAME NUMBER. The TARGET is’ the byte 
whose 20-bit address is (X*16). 


Note 


The Microsoft Linker does not support methods T3 and T7. 


The following nomenclature is used to describe a TARGET: 
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TARGET: SI(<segment name>), <displacement> [TO] 


TARGET: GI(<group name>), <displacement> [T1] 
TARGET: EI(<symbol name>), <displacement> [T2] 
TARGET: SI (<segment name>) [T4] 
TARGET: GI (<group name>) [T5] 
TARGET: EI (<Symbol name>) [T6] 


The following examples illustrate how this notation is used: 


TARGET: SI(CODE), 1024 The 1025th byte in 
the segment "CODE". 

TARGET: GI (DATAAREA) The location in MAS of 
a group called 
"DATAAREA". 

TARGET: EI (SIN) The address of the 
external subroutine 
"SIN" m 

TARGET: EI(PAYSCHEDULE), 24 The 24th byte 


following the location 
of an EXTERNAL data 
Structure called 
"PAYSCHEDULE". 


FRAME - Every 8086 memory reference is to a location 
contained within some FRAME; where the FRAME is designated 
by the content of some segment register. For the Linker’ to 
form a correct, usable memory reference, it must know what 
the TARGET is, and to which FRAME the reference is’ being 
made. Thus, every fixup specifies such a FRAME, in one of 
six ways. Some ways use data, X, which is in 
INDEX-Or-FRAME-NUMBER, aS_ above. Other ways require no 
data. 


The six ways of specifying frames are: 


(FO) X is a SEGMENT INDEX. The FRAME is’- the 
canonic FRAME of the LSEG defined by the INDEX. 
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(Fl) X is a GROUP INDEX. The FRAME is the’ canonic 
FRAME defined by the group (i.e., the canonic FRAME 
defined by the LSEG in the group that is eventually 
LOCATEd lowest in MAS). 


(F2) xX is an EXTERNAL INDEX. The FRAME is 
determined when the External Name's public 
definition is found. There are three cases: 


@e (F2a) The symbol is defined relative to some 
LSEG, and there is no associated GROUP. The 
LSEGs canonic FRAME is specified. 


@ (F2b) The symbol is defined absolutely, without 
reference to an LSEG, and there is no 
associated GROUP. The FRAME is’ specified by 
the FRAME NUMBER subfield of the PUBDEF record 
that gives the symbol's definition. 


@ (F2c) Regardless of how the symbol is defined, 
there is an associated GROUP. The canonic 
FRAME of the GROUP is specified. (The group is 
Specified by the GROUP INDEX subfield of the 
PUBDEF Record.) 


(F3) X is a FRAME NUMBER (specifying the obvious 
FRAME) . 


(F4) No X. The FRAME is the canonic FRAME of the 
LSEG containing LOCATION. 


(F5) No X. The FRAME is determined by the TARGET. 
There are four cases: 


@e (F5a) The TARGET specified a SEGMENT INDEX: in 
this case, the FRAME is determined as in (FO). 


e (F5b) The TARGET specified a GROUP INDEX: in 
this case, the FRAME is determined as in (Fl). 


e (F5c) The TARGET specified an EXTERNAL INDEX: 
in this case, the FRAME is determined as in 
(F2). 


@ (F5d) The TARGET is specified with an explicit 
FRAME NUMBER: in this case the FRAME is 
determined as in (F3). 
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Note 


The Microsoft Linker does not support frame methods 
F2b, F3, and F5d. 


Nomenclature describing FRAMES is Similar to the above 
nomenclature for TARGETs. 


FRAME: SI (<Segment name>) [FO] 
FRAME: GI (<group name>) [Fl] 
FRAME: EI (<symbol name>) [F2] 
FRAME: LOCATION [F4] 
FRAME: TARGET [F5] 
FRAME: NONE [F6] 


For an 8086 memory reference, the FRAME specified by a 
self-relative reference is usually the canonic FRAME of the 
LSEG containing the LOCATION, and the FRAME specified by a 
segment relative reference is the canonic FRAME of the LSEG 
containing the TARGET. 


6.9 SELF-RELATIVE FIXUPS 


A self-relative fixup operates as follows: A memory address 
is implicitly defined by LOCATION; namely the address of 
the byte following LOCATION (because at the time of a 
self-relative reference, the 8086 IP (Instruction Pointer) 
is pointing to the byte following the reference). 


For 8086 self-relative references, if either LOCATION or 
TARGET are outside the specified FRAME, the Linker gives a 
warning. Otherwise, there is a unique 16-bit displacement 
which, when added to the address implicitly defined by 
LOCATION, will yield the relative position of TARGET in the 
FRAME. 


If the LOCATION is an OFFSET, the displacement is added to 
LOCATION modulo 65536; no errors are reported. 
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If the LOCATION is a LOBYTE, the displacement must be within 
the range {-128:127}, otherwise the Linker will give a 
warning. The displacement is added to LOCATION modulo 256. 


If the LOCATION is a BASE, POINTER, or HIBYTE, it is unclear 
what the translator had in mind, and the action taken by the 
Linker is undefined. 


6.10 SEGMENT-RELATIVE FIXUPS 


A segment-relative fixup operates in the following way: a 
non-negative 16-bit number, FBVAL, is defined as the FRAME 
NUMBER of the FRAME specified by the fixup, and a signed 
20-bit number, FOVAL, is defined as the distance from the 
base of the FRAME to the TARGET. If this signed 20-bit 
number is less than 0 or greater than 65535, the Linker 
reports an error. Otherwise, FBVAL and FOVAL are used _ to 
fixup LOCATION in the following fashion: 


1. If LOCATION is a POINTER, then FBVAL is added 
(modulo 65536) to the high-order word of POINTER, 
and FOVAL is added (modulo 65536) to the low-order 
word of POINTER. 


2. If LOCATION is a BASE, then FBVAL is added (modulo 
65536) to the BASE; FOVAL is ignored. 


3. If LOCATION is an OFFSET, then FOVAL is added 
(modulo 65536) to the OFFSET; FBVAL is ignored. 


4. If LOCATION is a HIBYTE, then (FOVAL/256) is added 
(modulo 256) to the HIBYTE; FBVAL is ignored. 
(The indicated division is "integer division", 
i.e., the remainder is discarded.) 


5. If LOCATION is a LOBYTE, then (FOVAL modulo 256) is 
added (modulo 256) to the LOBYTE; FBVAL is 
ignored. 


6.11 RECORD ORDER 


A object code file must contain a sequence of (one or more) 
modules, or a library containing zero or more modules. A 
module is defined as a collection of object code defined by 
a sequence of object records. The following syntax shows 
the valid orderings of records to form a module. In 
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addition, the given Semantic rules provide information about 
how to interpret the record sequence. 


Note 


The syntactic description language used below is 
defined in WIRTH: CACM, November 1977, vol.#20, no.#1l1, 


pp.#822-823. The character strings represented by 
capital letters above are not literals but are 
identifiers that are further defined in the section 
describing the record formats. 


object file = tmodule 

tmodule = THEADR seg-grp {component } modtail 

seg grp = {LNAMES} {SEGDEF} {TYPDEF | EXTDEF | GRPDEF} 
component = data | debug record 

data = content def | thread def | 


TYPDEF | PUBDEF | EXTDEF 


debug record = LINNUM 


content def = data record {FIXuUPP} 

thread _ def = FIXUPP (containing only thread fields) 
data_record = LIDATA | LEDATA 

modtail = MODEND 


The following rules apply: 


1. A FIXUPP record always refers to the previous DATA 
record. 


-2. All LNAMES, SEGDEF, GRPDEF, TYPDEF, and EXTDEF 
records must precede all records that refer to 
them. 


3. COMENT records may appear anywhere in ae file, 
except as the first or last record ina file or 
module, or within a contentdef. 
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6.12 INTRODUCTION TO THE RECORD FORMATS 


The following pages present diagrams of record formats’ in 
schematic form. Here iS a sample record format, to 
illustrate the various conventions. 


SAMPLE RECORD FORMAT 


(SAMREC) 
/ | | 
REC RECORD NAME NUMBER CHK 
TYP LENGTH SUM 
XXH 
ys | | 
rpt 


TITLE and OFFICIAL ABBREVIATION 


At the top is the name of the record format described, with 
an official abbreviation. To promote uniformity among 
various programs, including translators and debuggers, the 
abbreviation should be uSed in both code and documentation. 
The record format abbreviation is always six letters. 


The BOXES 


Each format is drawn with boxes of two sizes. The narrow 
boxes represent single bytes. The wide boxes represent two 
bytes each. The wide boxes with three slashes in the top 
and bottom represent a variable number of bytes, one or 
more, depending upon content. The wide boxes with four 
vertical bars in the top and bottom represent 4-byte fields. 


RECTYP 


The first byte in each record contains a value between 0 and 
255, indicating which record type the record is. 


RECORD LENGTH 


The second field in each record contains the number of bytes 
in the record, exclusive of the first two fields. 
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Any field that indicates a "NAME" has the following internal 
structure: the first byte contains a number between 0 and 
127, inclusive, that indicates the number of remaining bytes 
in the field. The remaining bytes are interpreted as a byte 
string. 


Most translators constrain the character set to be a_ subset 
of the ASCII character set. 


NUMBER 


A 4-byte NUMBER field represents a 32-bit unsigned integer, 
where the first 8 bits (least-significant) are stored in the 
first byte (lowest address), the next 8 bits are stored in 
the second byte, and So on. 


REPEATED OR CONDITIONAL FIELDS 


Some portions of a record format contain a field or a series 
of fields that may be repeated one or more times. Such 
portions are indicated by the "repeated" or "rpt" brackets 
below the boxes. 


Similarly, some portions of a record format are present only 
if some given condition is true; these fields are indicated 
by similar "conditional" or "cond" brackets below the boxes. 


CHKSUM 


The last field in each record is a check sum, which contains 
the 2's complement of the sum (modulo 256) of all other 
bytes in the record. Therefore, the sum (modulo 256) of all 
bytes in the record equals 0. 


BIT FIELDS 


Descriptions of contents of fields will sometimes be at the 
bit level. Boxes with vertical lines drawn through them 
represent bytes or words; the vertical lines indicate bit 
boundaries; thus the byte represented below, has three 
bit-fields of 3-, 1-, and 4-bits. 
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T-MODULE HEADER RECORD 
(THEADR) 


REC RECORD 
TYP LENGTH 
80H 


ai 
MODULE 
NAME 


/ 


Every module output from a translator must have a T-MODULE 
HEADER RECORD. 


T—MODULE NAME 


The T-MODULE NAME provides a name for the T-MODULE. 
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LIST OF NAMES RECORD 
(LNAMES) 


RECORD NAME CHK 
LENGTH SUM 


rpt 


This Record provides a list of names that may be used in 
following SEGDEF and GRPDEF records as ‘the names of 
Segments, Classes and/or Groups. 


The ordering of LNAMES records within a module, together 
with the ordering of names within each LNAMES Record, 
induces an ordering on the names. Thus, these names are 
considered to be numbered: 1, 2, 3, 4, ... These numbers 
are used as "Name Indices" in the Segment Name Index, Class 
Name Index and Group Name Index fields of the SEGDEF and 
GRPDEF Records. 


NAME 


This repeatable field provides a name, which may have zero 
length. 
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SEGMENT DEFINITION RECORD 
(SEGDEF) 


/ 


SEGMENT 
ATTR 


REC} RECORD 
TYP} LENGTH 
98H 


SEGMENT 
LENGTH NAME NAME |LAY SUM 


INDEX INDEX | NAME 
/ / 
SEGMENT INDEX values 1 through 32767, which are used in 
other record types to refer to specific LSEGs, are defined 


implicitly by the Sequence in which SEGDEF Records appear in 
the object file. 


SEG ATTR 


The SEG ATTR field provides information on various 
attributes of a segment, and has the following format: 


ACB FRAME OFF 
P NUMBER SET 


conditional 


The ACBP byte contains four numbers which are the A, C, B, 
and P attribute specifications. This byte has the following 
format: 


"A" (Alignment) is a 3-bit subfield that specifies the 
alignment attribute of the LSEG. The semantics are defined 
as follows: 


A=0 SEGDEF describes an absolute LSEG. 
A=1 SEGDEF describes a relocatable, byte-aligned LSEG. 
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A=2 SEGDEF describes a relocatable, word-aligned LSEG. 

A=3 SEGDEF describes a relocatable, paragraph-aligned 
LSEG. 

A=4 SEGGDEF describes a relocatable, page-aligned LSEG. 


If A=0, the FRAME NUMBER and OFFSET fields will be present. 
Using MS-LINK, absolute segments may be used for addressing 
purposes only; for example, defining the starting address 
of a ROM and defining symbolic names for addresses within 
the ROM. MS-LINK will ignore any data specified as 
belonging to an absolute LSEG. 


"C" (Combination) is a 3-bit subfield that specifies the 
combination attribute of the LSEG. Absolute segments (A=0) 
must have combination zero (C=0). For relocatable segments, 
the C field encodes a number (0,1,2,4,5,6 or 7) that 
indicates how the segment can be combined, The 
interpretation of this attribute is best given by 
considering how two LSEGsS are combined: Let X,Y be _ LSEGs, 
and let Z be the LSEG resulting from the combination of X,Y. 
Let LX and LY be the lengths of X and Y, and let MXY denote 
the maximum of LX, LY. Let G be the length of any gap 
required between the X- and Y-components of Z to accommodate 
the alignment attribute of Y. Let LZ denote the length of 
the (combined) LSEG 2; let dx (0<=dx<LX) be the offset in X 
of a byte, and let dy similarly be the offset in Y of a 
byte. The following table gives the length LZ of the 
combined LSEG 2Z, and the offsets dx' and dy' in 2 for the 
bytes corresponding to dx in X and dy in Y. Intel defines 
additionally alignment types 5 and 6 and also processes code 
and data placed in segment with align-type. 


Table 6.2 Combination Attribute Example 


C LZ dx' dy' 

2 LX+LY+G dx dy+LX+G "Public" 
5 LX+LY+G dx dy+LX+G "Stack" 
6 MXY dx dy "Common" 


Table 6.2 has no lines for C=0, C=1, C=3, C=4 and C=7. C=0 
indicates that the relocatable LSEG may not be combined; 
C=1 and C=3 are undefined. C=4 and C=7 are treated like 
C=2. Cl, C4, and C7 all have different meanings according 
to the Intel standard. 


"B" (Big) is a l-bit subfield which, if 1, indicates’ that 
the Segment Length is exactly 64K (65536). In this case the 
SEGMENT LENGTH field must contain zero. 
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The "P" field must always be zero. The "P" field is’ the 
"Page resident" field in Intel-Land. 


The FRAME NUMBER and OFFSET fields (present only for 
absolute segments, A=0) specify the placement in MAS of the 
absolute segment. The range of OFFSET is constrained to be 
between 0 and 15 inclusive. If a value larger than 15 is 
desired for OFFSET, then an adjustment of the FRAME NUMBER 
should be done. 


SEGMENT LENGTH 


The SEGMENT LENGTH field gives the length of the segment in 
bytes. The length may be zero; if so, MS-LINK will not 
delete the segment from the module. The SEGMENT LENGTH 
field is only big enough to hold numbers from 0 to 64K-1 
inclusive. The B attribute bit in the ACBP field (see SEG 
ATTR section) must be used to give the segment a length of 
64K. 


_ SEGMENT NAME INDEX 


The Segment Name is a name the programmer or translator 
assigns to the segment. Examples: CODE, DATA, TAXDATA, 
MODULENAME CODE, STACK. This field provides the Segment 
Name, by indexing into the list of names provided by the 
LNAMES Record(s). 


CLASS NAME INDEX 


The Class Name is a name the programmer or translator can 
assign to a segment. If none is assigned, the name is null, 
and has length 0. The purpose of Class Names is to allow 
the programmer to define a "handle" used in the ordering of 
the LSEGs in MAS. Examples: RED, WHITE, BLUE; ROM 
FASTRAM, DISPLAYRAM. This field provides the Class Name, by 
indexing into the list of names provided by the LNAMES 
Record(s). 
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OVERLAY NAME INDEX 


Note 


This is ignored in MS-LINK versions 2.40 and later, but 


supported in all earlier versions. However, semantics 
differ from Intel semantics. 


The Overlay Name is a name the translator and/or MS-LINK, at 
the programmer's request, applies to a segment. The Overlay 
Name, like the Class Name, may be null. This field provides 
the Overlay Name, by indexing into the list of names 
provided by the LNAMES Record(s). 


Note 


The "Complete Name" of a segment is a 3-component 


entity comprising a Segment Name, a Class Name and an 
Overlay Name. (The latter two components may be null.) 
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GROUP DEFINITION RECORD 
(GRPDEF) 


RECORD GROUP GROUP 
LENGTH COMPONENT 
DESCRIPTOR 


GROUP NAME INDEX 


The Group Name is a name by which a collection of LSEGsS may 
be referenced. The important property of Such a group is 
that, when the LSEGs are eventually fixed in MAS, there must 
exist some FRAME which "covers" every LSEG of the group. 


The GROUP NAME INDEX field provides the Group Name, by 
indexing into the list of names provided by the LNAMES 
Record(s). 


GROUP COMPONENT DESCRIPTOR 


Each GROUP COMPONENT DESCRIPTOR has the following format: 


SEGMENT 


INDEX 


The first byte of the DESCRIPTOR contains OFFH; the 
DESCRIPTOR contains one field, which is a SEGMENT INDEX that 
selects the LSEG described by a preceding SEGDEF record. 


Intel defines 4 other group descriptor types, each with its 
own meaning. They are OFEH, OFDH, OFBH, and OFAH. The 
Microsoft Linker will treat all of these values the Same as 
OFFH (i.e., it always expects OFFH followed by a segment 
index, and it does not, in fact, check to see if the value 
is actually OFF). 


INTEL RELOCATABLE OBJECT MODULE FORMATS Page 6-25 
TYPE DEFINITION RECORD 
(TYPDEF ) 


A / 


REC RECORD NAME EIGHT 
TYP LENGTH (USUALLY LEAF 
8EH NULL) DESCRIPTOR 


/ is 


repeated 


The Microsoft Linker uses TYPDEF records only for communal 
variable allocation. This is not Intel's intended purpose. 
See Section 6.14, "Microsoft Type Representations for 
Communal Variables." 


AS many “EIGHT LEAF DESCRIPTOR" fields as necessary are used 
to describe a branch. (Every such field except the last in 
the record describes eight leaves; the last such field 
describes from one to eight leaves.) 


TYPE INDEX values 1 through 32767, which are contained in 
other record types to associate object types with object 
names, are defined implicitly by the sequence in which 
TYPDEF records appear in the object file. 


NAME 


Use of this field is reserved. Translators should place a 
Single byte containing 0 in it (which is the representation 
of a name of length zero). 
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EIGHT LEAF DESCRIPTOR 


This field can describe up to eight Leaves. 


/ 
LEAF 
DESCRIPTOR 
/ 
r 


pt 


The EN field is a byte: the 8 bits, left to right, indicate 


if the following 8 Leaves (left to right) are Easy (bit=0) 
or Nice (bit=1). 


The LEAF DESCRIPTOR field, which occurs between 1 and 8 
times, has one of the following formats: 


0 
to 
128 
0 
129 to 
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0 
132 to 
L6M-1 
-2G-1 
136 to 
2G-1 


The first format (Single byte), containing a value between 0 
and 127, represents a Numeric Leaf whose value is the number 
given. 


The second format, with a leading byte containing 129, 
represents a Numeric Leaf. The number is contained in the 
following two bytes. 


The third format, with a leading byte containing 132, 
represents a Numeric Leaf. The number is contained in the 
following three bytes. 


The fourth format, with a leading byte containing 136, 
represents a Signed Numeric Leaf. The number is contained 
in the following four bytes, sign extended if necessary. 
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PUBLIC NAMES DEFINITION RECORD 


RECORD 
LENGTH 


(PUBDEF) 


This record provides a list of one or more PUBLIC NAMEs; 
for each one, three data are provided: (1) a base value for 
the name, (2) the offset value of the name, and (3) the type 
of entity represented by the name. 


PUBLIC BASE 
The PUBLIC BASE has the following format: 


f / 


GROUP SEGMENT 
INDEX INDEX 


FRAME 
NUMBER 


/ / 


conditional 


The GROUP INDEX field has a format given earlier, and 
provides a number between 0 and 32767 inclusive. A non-zero 
GROUP INDEX associates a group with the public symbol, and 
is used as described in Section 6.8, "Conceptual Framework 
for Fixups," case (F2c). A zero GROUP INDEX indicates’ that 
there is no associated group. 


The SEGMENT INDEX field has a format given earlier, and 
provides a number between 0 and 32767, inclusive. 


A non-zero SEGMENT INDEX selects an LSEG. In this case, the 
location of each public symbol defined in the record is 
taken as a non-negative displacement (given by a PUBLIC 
OFFSET field) from the first byte of the selected LSEG, and 
the FRAME NUMBER field must be absent. | 
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A SEGMENT INDEX of 0 (legal only if GROUP INDEX is also 0) 
means that the location of each public symbol defined in the 
record is taken as a displacement from the base of the FRAME 
defined by the value in the FRAME NUMBER field. 


The FRAME NUMBER is present if both the SEGMENT INDEX and 
GROUP INDEX are zero. 


A non-zero GROUP INDEX selects some group; this group is 
taken as the "frame of reference" for references to all 
public symbols defined in this’ record; that is, MS-LINK 
will perform the following actions: 


1. Any fixup of the form: 
TARGET: EI (P) 
FRAME: ‘TARGET 


(where "P" is a public symbol in this PUBDEF 
record) will be converted by MS-LINK to a fixup of 
the form: 


TARGET: SI(L),d 
FRAME: GI (G) 


where "SI(L)" and "dad" are provided by the SEGMENT 
INDEX and PUBLIC OFFSET fields. (The "normal" 
action would have the frame specifier in the new 
fixup be the same as in the old fixup: FRAME: 
TARGET. ) 


2. When the value of a public symbol, as defined by 
the SEGMENT INDEX, PUBLIC OFFSET, and (optionally) 
FRAME NUMBER fields, is converted to a 
{base,offset} pair, the base part will be taken as 
the base of the indicated group. If a non-negative 
16-bit offset cannot then complete the definition 
of the public symbol's value, an error occurs. 


A GROUP INDEX of zero selects no group. MS-LINK will not 
alter the FRAME specification of fixups referencing the 
symbol, and will take, as the base part of the absolute 
value of the public symbol, the canonic frame of the segment 
(either LSEG or PSEG) determined by the SEGMENT INDEX field. 
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PUBLIC NAME 


The PUBLIC NAME field gives the name of the object whose 
location in MAS is’ made available to other modules. The 
name must contain one or more characters. 


PUBLIC OFFSET 


The PUBLIC OFFSET field is a 16-bit value, which is’ either 
the offset of the Public Symbol with respect to an LSEG (if 
SEGMENT INDEX > 0), or the offset of the Public Symbol with 
respect to the specified FRAME (if SEGMENT INDEX = 0). 


TYPE INDEX 


The TYPE INDEX field identifies a single preceding TYPDEF 
(Type Definition) Record containing a descriptor for the 
type of entity represented by the Public Symbol. This field 
is ignored by the Linker. 
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EXTERNAL NAMES DEFINITION RECORD 


(EXTDEF ) 
7 
REC RECORD EXTERNAL 
TYP LENGTH 
8CH 


This record provides a list of external names, and for’ each 
name, the type of object it represents. MS-LINK will assign 
to each External Name the value provided by an identical 
Public Name (if such a name is found). 


EXTERNAL NAME 


This field provides the name, which must have _ non-zero 
length, of an external object. 


Inclusion of a Name in an External Names Record is an 
implicit request that the object file be linked to a module 
containing the same name declared as a Public Symbol. This 
request obtains whether or not the External Name is 
referenced within some FIXUPP Record in the module. 


The ordering of EXTDEF Records within a module, together 
with the ordering of External Names within each EXTDEF 
Record, induces an ordering on the set of all External Names 
requested by the module. Thus, External Names are 
considered to be numbered 1, 2, 3, 4, «eee These numbers 
are used as "External Indices" in the TARGET DATUM and/or 
FRAME DATUM fields of FIXUPP Records to refer to a 
particular External Name. 
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Note 


8086 External Names are numbered positively: 1,2,3,... 
This is a change from 8080 External Names, which were 


numbered starting from zero: 0,1,2,... This conforms 
with other 8086 Indices (Segment Index, Type Index, 
etc.) which use 0 as a default value with special 
meaning. 


External indices may not reference forward. For example, an 
external definition record defining the kth object must 
precede any record referring to that object with index k. 


TYPE INDEX 


This field identifies a single preceding TYPDEF (Type 
Definition) record containing a descriptor for the type of 
object named by the External Symbol. 


The TYPE INDEX is used only in communal variable allocation 
by the Microsoft Linker. 
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LINE NUMBERS RECORD 
(LINNUM) 


—— 


RECORD LINE 
LENGTH NUMBER 


LINE 
NUMBER 


LINE 
NUMBER 
OFFSET 


repeated 


This record provides the means by which a translator may 
pass the correspondence between a line number in source code 
and the corresponding translated code. 


LINE NUMBER BASE 


The LINE NUMBER BASE has the following format: 


/ 


GROUP 
INDEX 
(ignored) 


a 


[fp 


SEGMENT 
INDEX 


7 


The SEGMENT INDEX determines the location of the first byte 
of code corresponding to some source line number. 


LINE NUMBER 


A line number between 0 and 32767, inclusive, is provided in 
binary by this field. The high-order bit is reserved for 
future use and must be zero. 


LINE NUMBER OFFSET 


The LINE NUMBER OFFSET field is a 16-bit value, which is the 
offset of the line number with respect to an LSEG (if 
SEGMENT INDEX > 0). 
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LOGICAL ENUMERATED DATA RECORD 
(LEDATA) 


/ 


REC RECORD SEGMENT ENUMERATED 
TYP LENGTH INDEX DATA 
AOH OFFSET 


rpt 


This record provides contiguous data from which a portion of 
an 8086 memory image may be constructed. 


SEGMENT INDEX 


This field must be non-zero and specifies an index relative 
to the SEGMENT DEFINITION RECORDS’ found previous to the 
LEDATA RECORD. 


ENUMERATED DATA OFFSET 


This field specifies an offset that is relative to the base 
of the LSEG that is specified by the SEGMENT INDEX and 
defines the relative location of the first byte of the DAT 
field. Successive data bytes in the DAT field occupy 
successively higher locations of memory. 


DAT 


This field provides up to 1024 consecutive bytes of 
relocatable or absolute data. 
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LOGICAL ITERATED DATA RECORD 
(LIDATA) 


is 


SEGMENT 
INDEX 


7 
ITERATED 


DATA 
BLOCK 


va 


repeated 


RECORD 
LENGTH 


ITERATED 
DATA 
OFFSET 


This record provides contiguous data from which a portion of 
an 8086 memory image may be constructed. 


SEGMENT INDEX 


This field must be non-zero and specifies an index relative 
to the SEGDEF records found previous to the LIDATA RECORD. 


ITERATED DATA OFFSET 


This field specifies an offset that is relative to the base 
of the LSEG that is specified by the SEGMENT INDEX and 
defines the relative location of the first byte in the 
ITERATED DATA BLOCK. Successive data bytes in the ITERATED 
DATA BLOCK occupy successively higher locations of memory. 
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ITERATED DATA BLOCK 


This repeated field is a structure specifying the repeated 
data bytes. The structure has the following format: 


REPEAT 
COUNT 


BLOCK 


COUNT CONTENT 


Note 


The Linker cannot handle LIDATA records whose ITERATED 
DATA BLOCK is larger than 512 bytes. 


REPEAT COUNT 


This field specifies the number of times that the CONTENT 
portion of this ITERATED DATA BLOCK is to be repeated. 
REPEAT COUNT must be non-zero. 


BLOCK COUNT 


This field specifies the number of ITERATED DATA BLOCKS that 
are to be found in the CONTENT portion of this ITERATED DATA 
BLOCK. If this field has value zero, then the CONTENT 
portion of this ITERATED DATA BLOCK is interpreted as data 
bytes. If non-zero, then the CONTENT portion is interpreted 
as that number of ITERATED DATA BLOCKs. 


CONTENT 


This field may be interpreted in one of two ways, depending 
on the value of the previous BLOCK COUNT field. 


If BLOCK COUNT is zero, then this field is a 1-byte count 
followed by the indicated number of data bytes. 


If BLOCK COUNT is non-zero, then this field is interpreted 
as the first byte of another ITERATED DATA BLOCK. 
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Note 


From the outermost level, the number of nested ITERATED 


DATA BLOCKS is limited to 17, i.e., the number of 
levels of recursion is Limited to 17. 
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FIXUP RECORD 


(FIXUPP) 


RECORD THREAD CHK 
LENGTH or SUM 


This record specifies 0 or more fixups. Each fixup requests 
a modification (fixup) to a LOCATION within the previous 
DATA record. A data record may be followed by more than one 
fixup record that’ refers, Each fixup is specified by a 
FIXUP field that specifies four data: a location, a mode, a 
target and ae frame. The frame and the target may be 
specified totally within the FIXUP field, or may be 
specified by reference to a preceding THREAD field. 


A THREAD field specifies a default target or frame that may 
subsequently be referred to in identifying a target or a 
frame. Eight threads are provided; four for frame 
specification and four for target specification. Once a 
target or frame has been specified by a THREAD, it may _ be 
referred to by following FIXUP fields (in the same or 
following FIXUPP records), until another THREAD field with 
the same type (TARGET or FRAME) and Thread Number (0 - 3) 
appears (in the same or another FIXUPP record). 


THREAD 
THREAD is a field with the following format: 


/ 
TRD INDEX 


/ 


conditional 


The TRD DAT (ThReaD DATa) subfield is a byte with this 
internal structure: 
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The "Z" is a l-bit subfield, currently without any defined 
function, that is required to contain 0. 


The "D" subfield is one bit that identifies what type of 
thread is being specified. If D=0, then a target thread is 
being defined; if D=l, then a frame thread is being 
defined. 


METHOD is a 3-bit subfield containing a number between 0 and 
3 (D=0) or a number between 0 and 6 (D=1). 


If D=0, then METHOD = (0, 1, 2, 3, 4, 5, 6, 7) mod 4, where 
the 0, ..., 7 indicate methods TO, ..., T7 of specifying a 
target. Thus, METHOD indicates what kind of Index or Frame 
Number is required to specify the target, without indicating 
if the target will be specified in a primary or secondary 
way. Note that methods 2b, 3, and 7 are not Supported by 
MS-LINK. 


If D=1, then METHOD = 0O, 1, 2, 4, 5, corresponding to 
methods FO, ..., of Specifying a frame. Here, METHOD 
indicates what kind (if any) of Index is required to specify 
the frame. Note that methods 3 and 5d are not supported by 
MS-LINK. 


THRED is a number between 0 and 3, and associates a Thread 
Number to the frame or target defined by the THREAD field. 


INDEX contains a Segment Index, Group Index, or External 
Index depending on the specification in the METHOD subfield. 
This subfield will not be present if F4 or F5 are specified 
by METHOD. 
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FIXUP 


FIXUP is a field with the following format: 


en 


/ 


TARGET 
DATUM 


/ 


TARGET 
DIS- 
PLACEMENT 


conditional! conditional!conditional 


LOCAT is a byte pair with the following format: 


RECORD OFFSET 


lo byte hi byte 


M is a l-bit subfield that specifies the mode of the fixups: | 
self-relative (M=0) or segment-relative (M=1). 


Note 


Self-relative fixups may not be applied to LIDATA 
records. 


"S" is a 1l-bit subfield that specifies that the length of 
the TARGET DISPLACEMENT subfield. If it is present in this 
FIXUP field (see below), it will be either two bytes 
(containing a 16-bit non-negative number, S=0) or three 
bytes (containing a signed 24-bit number in 2's complement 
form, S=l1). 
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Note 


3-byte subfields are a possible future extension, and 


are not currently supported. Thus, S=0 is currently 
Mandatory. 


LOC is a 3-bit subfield indicating that the byte(s) in the 
preceding DATA Record to be fixed up are a “lobyte" (LOC=0), 
an “offset" (LOC=1), a "base" (LOC=2), a "pointer" (LOC=3), 
or a "hibyte" (LOC=4). Other values in LOC are invalid. 


The DATA RECORD OFFSET iS a number between 0 and =41023, 
inclusive, that gives the relative position of the lowest 
order byte of LOCATION (the actual bytes being fixed _ up) 
within the preceding DATA record. The DATA RECORD OFFSET is 
relative to the first byte in the data fields in the DATA 
RECORDs. 


Note 


If the preceding DATA record is an LIDATA record, it is 
possible for the value of DATA RECORD OFFSET to 
designate a "location" within a REPEAT COUNT subfield 
Or a BLOCK COUNT subfield of the ITERATED DATA field. 
Such a reference is an error. MS-LINK's action on such 
a malformed record is undefined. 


FIX DAT is a byte with the following format: 


See Note 1 See Note 2 


Note 1: Frame method 2b, F3, and F5d_ are not 
supported. 


Note 2: Target method T3 and T7 are not Supported. 
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-F is a l-bit subfield that specifies whether the frame _ for 
this FIXUP is specified by a thread (F=1) or explicitly 
(F=0). 


FRAME iS a number interpreted in one of two ways as. 
indicated by the F bit. If F is zero, FRAME is a number 
between 0 and 5 and corresponds to methods FO, ..., F5 of 
specifying a FRAME. If F=l1, then FRAME is a thread number 
(0-3). It specifies the frame most recently defined by a 
THREAD field that defined a frame thread with the same 
thread number. (Note that the THREAD field may appear in 
the same, or in an earlier FIXUPP record.) 


"T" is a 1l-bit subfield that specifies whether the target 
specified for this fixup is defined by reference to a thread 
(T=1), or is given explicitly in the FIXUP field (T=0). 


"P" is a 1l-bit subfield that indicates whether the target is 
specified in a primary way (requires a TARGET DISPLACEMENT, 
P=0) or specified in a secondary way (requires no TARGET 
DISPLACEMENT, P=1). Since a target thread does not have a 
primary/secondary attribute, the P bit is the only field 
that specifies the primary/secondary attribute of the target 
specification. 


TARGT is interpreted as a 2-bit subfield. When T=0, it 
provides a number between 0 and 3, corresponding to methods 
TO, .«--, T3 Or T4, ..., T7, depending on the value of P (P 
can be interpreted as the high-order bit of TO, ..., T7). 
When the target is specified by a thread (T=1), then TARGT 
specifies a thread number (0-3). 


FRAME DATUM is the "referent" portion of a frame 
specification, and is a Segment Index, a Group Index, an 
External Index. The FRAME DATUM subfield is present only 
when the frame is specified neither by a thread (F=0) nor 
explicitly by methods F4 or F5 or F6. 


TARGET DATUM is the "referent" portion of a target 
specification, and is a Segment Index, a Group Index, an 
External Index or a Frame Number. The TARGET DATUM subfield 
is present only when the target is not specified by a thread 
(T=0). 


TARGET DISPLACEMENT is the 2-byte displacement required by 
"primary" ways of specifying TARGETs. This 2-byte subfield 
is present if P=0. 
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Note 


All these methods are described in Section 6.8, 
"Conceptual Framework for Fixups." 


MODULE END RECORD 


nd 


(MODEND) 


REC RECORD START CHK 
TYP LENGTH TYP ADDRS SUM 
8AH 


+conditional+ 


This record serves two purposes. It denotes the end of a 
module and indicates whether the module just terminated has 
a specified entry point for initiation of execution. If the 
latter is true, the execution address is specified. 


| MOD TYP 


This field specifies the attributes of the module. The bit 
allocation and associated meanings are as follows: 


MATTR is a 2-bit subfield that specifies the following 
module attributes: 


MATTR MODULE ATTRIBUTE 

0 Non-main module with no START ADDRS 
1 Non-main module with START ADDRS 

2 Main module with no START ADDRS 

3 Main module with START ADDRS 
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"L" indicates whether the START ADDRS field is interpreted 
aS a logical address that requires fixing up by MS-LINK. 
(L=1). Note: with MS-LINK, L must always equal l. 


"Z" indicates that this bit has not currently been assigned 
a function. These bits are required to be zero. 


Physical start addresses (L=0) are not Supported. 


The START ADDRS field (present only if MATTR is ,l or 3) has 
the following format: | 


START ADDRS 


FRAME TARGET TARGET 
DATUM DATUM DIS- 


PLACEMENT 


+conditional+conditional+conditional+ 


The starting address of a module has all the attributes of 
any other logical reference found in a module. The mapping: 
of a logical starting address to a physical starting address 
is done in exactly the same manner as mapping any other 
logical address to a physical address as specified in the 
discussion of fixups and the FIXUPP record. The above 
subfields of the START ADDRS field have the same’ semantics 
as the FIX DAT, FRAME DATUM, TARGET DATUM, and TARGET 
DISPLACEMENT fields in the FIXUPP record. Only "primary" 
fixups are allowed. Frame method F4 is not allowed. 


COMMENT RECORD 
(COMENT ) 


RECORD 
LENGTH 


COMMENT 
TYPE 


CHK 
COMMENT SUM 


/ 


| 
This record allows translators to include comments in object 
text. 
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COMMENT TYPE 


This field indicates the type of comment carried by this 
record. This allows comments’ to be structured for those 
processes that wish to selectively act on comments. The 
format of this field is as follows: 


The NP (NOPURGE) bit, if 1, indicates that it is not able to 
be purged by object file utility programs which implement 
the capability of deleting COMENT record. 


The NL (NOLIST) bit, if 1, indicates that the text in the 
COMMENT field is not to be listed in the listing file of 


object file utility programs which implement the capability 
of listing object COMENT records. 


The COMMENT CLASS field is defined as follows: 


0 Language translator comment. 

1 Intel copyright comment. The NP bit must be 
set. 

2-155 Reserved for Intel use. (See note 1 below.) 


156-255 Reserved for users. Intel products will 
apply no semantics to these values. (See 
Note 2 below.) 


COMMENT 


This field provides the commentary information. 
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Notes: 


1. 


Class value 129 is used to specify a library to add 
to the Linker's library search list. The comment 
field will contain the name of the library. Note 
that unlike all other name _ specifications, the, 
library name is not prefixed with its length. Its 
length is determined by the record length. The 
"NODEFAULTLIBRARYSEARCH" switch causes the _ linker 
to ignore all comment records whose class value is 
129. 


Class value 156 is used to specify a DOS level 
number. When the class value is 156, the comment 
field will contain a two-byte integer specifying a 
DOS level number. 
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6.13 NUMERIC LIST OF RECORD TYPES 


*6E RHEADR 
*70 REGINT 
*72 REDATA 
*74 RIDATA 
*76 OVLDEF 
*78 ENDREC 
*7A BLKDEF 
*7C BLKEND 
*7E DEBSYM 
80 THEADR 
*82 LHEADR 
*84 PEDATA 
*86 PIDATA 
88 COMENT 
8A MODEND 
8C EXTDEF 
8E TYPDEF 
90 PUBDEF 
*92 LOCSYM 
94 LINNUM 
96 LNAMES 
98 SEGDEF 
9A GRPDEF 
9C FIXUPP 
*9OE (none) 
AO LEDATA 
A2 LIDATA 
*A4 LIBHED 
*A6 LIBNAM 
*A8 LIBLOC 
*AA LIBDIC 


Note 


Record types preceded by an asterisk (*) are not 


supported by the Microsoft Linker. They will be 
ignored if they are found in an object module. 
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6.14 MICROSOFT TYPE REPRESENTATIONS FOR COMMUNAL VARIABLES 


This section defines the Microsoft standard for communal 
variable allocation on the 8086 and 80286. 


A communal variable is an uninitialized public variable 
whose final size and location are not fixed at compile time. 
Communal variables are similar to FORTRAN common blocks’ in 
that if a communal variable is declared in more than one 
object module being linked together, then its actual size 
will be the largest size specified in the _ several 
declarations. In the C language, all uninitialized public 
variables are communal. The following example shows three 
different declarations of the same C communal variable: 


char foo[4]; /* In file a.c */ 
char foo[1l]; /* In file b.c */ 
char foo[1024]; /* In file c.c */ 


If the objects produced from a.c, b.c, and c.c are linked 
together, then the linker will allocate 1024 bytes for the 
char array "foo". 


A communal variable is defined in the object text by an 
external definition record (EXTDEF) and the type definition 
record (TYPDEF) to which it refers. 


The TYPDEF for a communal variable has the following format: 


/ 
EIGHT 


REC RECORD 


TYP LENGTH LEAF 
8EH DESCRIPTOR 
7. 


The EIGHT LEAF DESCRIPTOR field has the following format: 


i 
LEAF 
DESCRIPTOR 


"4 


The EN field specifies whether the next 8 leaves in the LEAF 
DESCRIPTOR field are EASY (bit = 0) or NICE (bit = 1). This , 
byte is always zero for TYPDEFS for communal variables. \ 
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The LEAF DESCRIPTOR field has one of the following two 
formats. The format for communal variables in the default 
data segment (near variables) is as follows: 


(optional) 


The VARiable TYPe field may be either SCALAR (7BH), STRUCT 
(79H), Or ARRAY (77H). The VAR SUBTYP field (if any) is 
ignored by the Linker. The format for communal variables 
not in the default data segment (far variables) is as 


follows: 
/ / 
NUMBER ELEMENT 
OF TYPE 
ELEMENTS INDEX 
/ / 


The VARiable TYPe field must be ARRAY (77H). The length 
field specifies the NUMBER OF ELEMENTS, and the ELEMENT TYPE 
INDEX iS an index to a previously defined TYPDEF whose 
format is that of a near communal variable. 


The format for the LENGTH IN BITS or NUMBER OF ELEMENTS 
fields is the same as the format for the LEAF DESCRIPTOR 
field, described in the TYPDEF record format section of this 
manual. 
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Link time semantics: 


All EXTDEFs referencing a TYPDEF of one of the previously 
described formats are treated as communal variables. All 
Others are treated as externally defined symbols for which a 
matching public symbol definition (PUBDEF) is expected. A 
PUBDEF matching a communal variable definition will override 
the communal variable definition. Two communal variable 
definitions are said to match if the names given in the 
definitions match. If two matching definitions disagree 
about whether a communal variable is near or far, the linker 
will assume the variable is near. 


If the variable is near, then its size is the largest of the 
Sizes specified for it. If the variable is far, then the 
Linker issues a warning if there are conflicting array 
element size specifications; if there are no_- such 
conflicts, then the variable's size is the element size 
times the largest number of elements specified. The sum of 
the sizes of all near variables must not exceed 64K bytes. 
The sum of the sizes of all far variables must not exceed 
the size of the machine's addressable memory space. 


“Huge” communal variables: 


A far communal variable whose size is larger than 64K bytes 
will reside in segments that are contiguous (8086) or have 
consecutive selectors (80286). No other data items will 
reside in the segments occupied by a huge communal variable. 


If the linker finds matching huge and near communal variable 
definitions, it issues a warning message, Since it is 
impossible for a near variable to be larger than 64K bytes. 


PS 
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CHAPTER 7 


PROGRAMMING HINTS 


7.1 INTRODUCTION 
This chapter describes recommended MS-DOS 3.1 programming 
procedures. By using these programming hints, you can 
ensure compatibility with future versions of MS-DOS. 
The hints are organized into the following categories: 
Interrupts 
System Calls 
Device Management 
Memory Management 
Process Management 


File and Directory Management 


Miscellaneous 


7.2 INTERRUPTS 


Never explicitly issue Interrupt 22H (Terminate Process Exit 
Address). 


This should only be done by the DOS. To change the 
terminate address, use Function 35H (Get Interrupt 
Vector) to get the current address and save it, then 
use Function 25H (Set Interrupt Vector) to change 
the Interrupt 22H entry in the vector table to point 
to the new terminate address. 
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Use Interrupt 24H (Critical Error Handler Address) with 
care. 


The Interrupt 24H handler must preserve the _ ES 
register. 


Only system calls O1H-O0CH can be made by an 
Interrupt 24H handler. Making any other calls will 
destroy the MS-DOS stack and prevent successful use 
of the Retry or Ignore options. 


The registers SS, SP, DS, BX, CX, and DX must _ be 
preserved when using the Retry or Ignore options. 


When an Interrupt 24H (Critical Error Handler Address) is 
received, alwayS IRET back to MS-DOS with one of the 
standard responses. 


Programs that do not IRET from Interrupt 24H leave 
the system in an unpredictable state until a 
function call other than O1H-OCH is made. The 
Ignore option may leave data in internal system 
buffers that is incorrect or invalid. 


Avoid trapping Interrupt 23H (Control-C Handler Address) and 
Interrupt 24H (Critical Error Handler Address). Don't rely 
on trapping errors via Interrupt 24H as part of a copy 
protection scheme. 


These might not be included in future releases of 
the operating system. 


Interrupt 23H (Control-C Handler Address) must never be 
issued by a user program. 


Interrupt 23H must be issued only by MS-DOS. 


Save any registers your program uses before issuing 
Interrupt 25H (Absolute Disk Read) or Interrupt 26H 
(Absolute Disk Write). 


These interrupts destroy all registers except for 
the segment registers. 


Avoid writing or reading an interrupt vector 
directly to or from memory. 


Use Functions 25H and 35H (Set Interrupt Vector and Get 


Interrupt Vector) to set and get values in the interrupt 
table. 
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7.3 SYSTEM CALLS 
Use new system calls. 


Avoid using system calls that have been superseded 
by new calls unless a program must maintain backward 
compatibility with pre-2.0 versions of MS-DOS. See 
Section 1.8, "Old System Calls," of this manual for 
a list of these new calls. 


Avoid using system calls 01H-OCH and 26H (Create New PSP). 


Use the new "tools" approach for reading and writing 
On standard input and output. Use Function 4B00H 
(Load and Execute Program) instead of 26H to execute 
a child process. 


Use file-sharing calls if more than one process is in 
effect. 


See "File Sharing," in Section 1.5.2, "File-Related 


Function Requests" in Chapter 1 for more 
information, 


Use networking calls where appropriate. 


Some forms of IOCTL can only be used with Microsoft 
Networks. See Section 1.6, "Microsoft Networks," in 
this manual for a list of these calls. 


When selecting a disk with Function OEH (Select Disk), treat 
the value returned in AL with care. 


The value in AL specifies the maximum number of 
logical drives; it does not specify which drives 
are valid. 


7.4 DEVICE MANAGEMENT 
Use installable device drivers. 


MS-DOS provides a modular device driver structure 
for the BIOS, allowing you to configure and install 
device drivers at boot time. Block device drivers 
transmit a block of data at a time, while character 
device drivers transmit a byte of data at a time, 


Examples of both types of device drivers are given 
in Chapter 2, "MS-DOS Device Drivers." 
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Use buffered I/0. 


The device drivers can handle streams of data up to 
64K, When sending a large amount of output to the 
screen, you can send it with one system call. This 
will increase performance. 


Programs that use direct console I/O via Function 06H and 
07H (Direct Console I/O and Direct Console Input) and that 


want to read Control-C as data should ensure that Control-C 
checking is off. 


The program should ensure that Control-C checking is 
off by using Function 33H (Control-C Check). 


Be compatible with international Support. 


To provide support for international character sets, 
MS-DOS recognizes all possible byte values as 
Significant characters in filenames and data 
streams. Pre-2.x versions ignored the high bit in 
the MS-DOS filename. 


7.5 MEMORY MANAGEMENT 
Use memory management. 


MS-DOS keeps track of allocated memory by writing a 
memory control block at the beginning of each area 
of memory. Programs should use Functions 48H 
(Allocate Memory), 49H (Free Allocated Memory), and 
4AH (Set Block) to release unneeded memory. 


This will allow for future compatibility. 


See Section 1.3, "Memory Management," for more 
information. 


Only use allocated memory. 


Don't directly access memory that was not provided 
aS a result of a system call. Do not use fixed 
addressing, use only relative references. 


A program that uses memory that has not been 
allocated to it may destroy other memory control 
blocks or cause other applications to fail. 
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7.6 PROCESS MANAGEMENT 
Use the EXEC Function Call to load and execute programs. 


The EXEC Function (4B00H) is the preferred way to 
load programs and program overlays. Using the EXEC 
call instead of hard-coding information about how to 
load an .EXE file (or always assuming. that your file 
is a .COM file) will isolate your program from 
changes in future releases of MS-DOS and .EXE file 
formats. 


Use Function 31H (Keep Process), instead of Interrupt 27H 
(Terminate But Stay Resident). Function 31H allows programs 
to terminate and stay resident that are greater than 64K. 


Programs should terminate using End Process (4CH). 


Programs that terminate by 
- along jump to offset 0 in the PSP, 
- issuing an Interrupt 20H with CS:0 pointing at the PSP, 
- issuing an Interrupt 21H with AH=0, CS:0 pointing at the 
PSP, or 
- along call to location 50H in the PSP with AH=0 


must ensure that the CS register contains the segment 
address of the PSP. 


7.7 FILE AND DIRECTORY MANAGEMENT 
Use the MS-DOS file management system. 


Using the MS-DOS file system will ensure program 
compatibility with future MS-DOS versions through 
compatible disk formats and consistent internal 
storage. This will ensure compatibility with future 
MS-DOS versions. 


Use file handles instead of FCBs. 


A handle is a 16-bit number that is returned by 
MS-DOS when a file is opened or created using 
Functions 3CH, 3DH, 5AH, or 5BH (Create Handle, Open 
Handle, Create Temporary File, or Create New File). 
The MS-DOS file-related function requests that use 
handles are listed in Table 1.5 in Chapter l, 
"System Calls." 


These calls should be used instead of the old 
file-related functions that use FCBs (file control 
blocks). This is because a file operation can 
simply pass its handle rather than having to 
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maintain FCB information. If FCBs must be used, be 
Sure the program closes them and does not move them 
around in memory. 


Close all files that have changed in length before issuing 
an Interrupt 20H (Program Terminate), Function 00H 


(Terminate Program), Function 4CH (End Process), or Function 
ODH (Reset Disk). 


If a changed file is not closed, its length will not 
be recorded correctly in the directory. 


Close all files when they are no longer needed. 


Closing unneeded files will optimize performance in 
a networking environment. 


Only change disks if all files on the disk are closed. 


Information in internal system buffers may be 
written incorrectly to a changed disk. 


7.7.1 Locking Files 


Programs should not rely on being denied access to a_ locked 
region. 


Determine the status of the region by attempting to 
lock it, and examine the error code. 


Programs should not close a file with a locked region or 
terminate with an open file that contains a locked region. 


The result is undefined. Programs that might be 
terminated by an Interrupt 23H or Interrupt 24H 
(Control-C Handler Address or Critical Error Handler 
Address) should trap these interrupts and unlock any 
locked regions before exiting. 


7.8 MISCELLANEOUS 
Avoid timing dependencies. 


Various machines use CPUs of different speeds. 
Also, programs that rely upon the speed of the clock 
for timing will not be dependable in a _ networking 
environment. 
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Use the documented interface to the operating system. If 


either 
will be 


Use the 


Use the 


the hardware or media change, the operating system 
able to use the features without modification. 


Don't use the OEM (Original Equipment Manufacturer) 
-provided ROM support. 


Don't directly address the video memory. 


Don't use undocumented function calls, interrupts, 
or features. These items may change or not continue 
to exist in future versions of MS-DOS. Use of these 
features would make your program highly 
non-portable. 


-EXE format rather than the .COM format. 


-EXE files are relocatable and .COM files are direct 
memory images that load at a specific place and have 
no room for additional control information to be 
placed in them. .EXE files have headers that can be 
expanded for compatibility with future versions of 
MS-DOS. 


environment to pass information to applications. 


The environment allows a parent process to pass 
information to a child process. COMMAND.COM is 
usually the parent process to every application, so 
default drive and path information can easily be 
passed to the application. 
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